scummvm/engines/sword25/gfx/graphicengine.h

/* ScummVM - Graphic Adventure Engine
 *
 * ScummVM is the legal property of its developers, whose names
 * are too numerous to list here. Please refer to the COPYRIGHT
 * file distributed with this source distribution.
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * $URL$
 * $Id$
 *
 */

/*
 * This code is based on Broken Sword 2.5 engine
 *
 * Copyright (c) Malte Thiesen, Daniel Queteschiner and Michael Elsdoerfer
 *
 * Licensed under GNU GPL v2
 *
 */

/*
 * BS_GraphicEngine
 * ----------------
 * This the graphics engine interface.
 *
 * Autor: Malte Thiesen
 */

#ifndef SWORD25_GRAPHICENGINE_H
#define SWORD25_GRAPHICENGINE_H

// Includes
#include "common/array.h"
#include "common/str.h"
#include "graphics/surface.h"
#include "sword25/kernel/common.h"
#include "sword25/kernel/bs_stdint.h"
#include "sword25/kernel/resservice.h"
#include "sword25/kernel/persistable.h"
#include "sword25/math/rect.h"
#include "sword25/gfx/framecounter.h"
#include "sword25/gfx/renderobjectptr.h"

namespace Sword25 {

class BS_Kernel;
class Image;
class Panel;
class Screenshot;

// Typen
typedef unsigned int BS_COLOR;

// Makros
#define BS_RGB(R,G,B)       (0xFF000000 | ((R) << 16) | ((G) << 8) | (B))
#define BS_ARGB(A,R,G,B)    (((A) << 24) | ((R) << 16) | ((G) << 8) | (B))

/**
    @brief Dies ist das Graphik-Engine Interface, dass alle Methoden und Klassen enthält, die eine Graphik-Engine implementieren muss.

    Hier sind nur wenige Rumpffunktionen realisiert, wie z.B. das Abfragen der Parameter des Ausgabepuffers.
    Die Hauptfunktionen muss eine Implementation dieses Inferfaces stellen.<br>
    Die bisher einzige Implementation ist BS_DDrawGfx.
*/

class GraphicEngine : public BS_ResourceService, public BS_Persistable {
public:
	// Enums
	// -----

	// Colour formats
	//
	/**
	 * The colour format used by the engine
	 */
	enum COLOR_FORMATS {
		/// Undefined/unknown colour format
		CF_UNKNOWN = 0,
		/// 16-bit colour format (R5G5B5)
		CF_RGB15,
		/// 16-bit colour format (R5G6R5)
		CF_RGB16,
		/**
		 * Special alpha colour format of the engine, which supports very quick display using MMX instructions.
		 * The pixels are 16-bits wide and have the same format as #CF_RGB15. In addition, each pixel has an 8-bit
		 * alpha value.
		 * It summarises groupings of pixels pixels and four alpha values in a 12-byte data block.
		 * The data is stored in the following order:
		 * Alpha0 Alpha1 Alpha2 Alpha3 Pixel0 Pixel1 Pixel2 Pixel3
		 * If the number of pixels in a line is not divisible by 4, then unused pixels and alpha values can have
		 * arbitrary values.
		 */
		CF_RGB15_INTERLEAVED,
		/**
		 * Special alpha colour format of the engine, which supports very quick display using MMX instructions.
		 * The pixels are 16-bits wide and have the same format as #CF_RGB16. In addition, each pixel has an 8-bit
		 * alpha value.
		 * It summarises groupings of pixels pixels and four alpha values in a 12-byte data block.
		 * The data is stored in the following order:
		 * Alpha0 Alpha1 Alpha2 Alpha3 Pixel0 Pixel1 Pixel2 Pixel3
		 * If the number of pixels in a line is not divisible by 4, then unused pixels and alpha values can have
		 * arbitrary values.
		 */
		CF_RGB16_INTERLEAVED,
		/**
		 * 24-bit colour format (R8G8B8)
		 */
		CF_RGB24,
		/**
		 * 32-bit colour format (A8R8G8B8) (little endian)
		*/
		CF_ARGB32,
		/**
		    32-bit colour format (A8B8G8R8) (little endian)
		*/
		CF_ABGR32
	};

	// Interface
	// ---------

	/**
	 * Initialises the graphics engine and sets the screen mode. Returns true if initialisation failed.
	 * Notes: This method should be called immediately after the initialisation of all services.
	 *
	 * @param Height            The height of the output buffer in pixels. The default value is 600
	 * @param BitDepth          The bit depth of the desired output buffer in bits. The default value is 16
	 * @param BackbufferCount   The number of back buffers to be created. The default value is 2
	 * @param Windowed          Indicates whether the engine is to run in windowed mode.
	 */
	virtual bool        Init(int Width = 800, int Height = 600, int BitDepth = 16, int BackbufferCount = 2, bool Windowed = false) = 0;

	/**
	 * Begins rendering a new frame.
	 * Notes: This method must be called at the beginning of the main loop, before any rendering methods are used.
	 * Notes: Implementations of this method must call _UpdateLastFrameDuration()
	 * @param UpdateAll         Specifies whether the renderer should redraw everything on the next frame.
	 * This feature can be useful if the renderer with Dirty Rectangles works, but sometimes the client may
	*/
	virtual bool        StartFrame(bool UpdateAll = false) = 0;

	/**
	 * Ends the rendering of a frame and draws it on the screen.
	 *
	 * This method must be at the end of the main loop. After this call, no further Render method may be called.
	 * This should only be called once for a given previous call to #StartFrame.
	*/
	virtual bool        EndFrame() = 0;

	// Debug methods

	/**
	 * Draws a line in the frame buffer
	 *
	 * This method must be called between calls to StartFrame() and EndFrame(), and is intended only for debugging
	 * purposes. The line will only appear for a single frame. If the line is to be shown permanently, it must be
	 * called for every frame.
	* @param Start      The starting point of the line
	* @param End        The ending point of the line
	* @param Color      The colour of the line. The default is BS_RGB (255,255,255) (White)
	*/
	virtual void        DrawDebugLine(const BS_Vertex &Start, const BS_Vertex &End, unsigned int Color = BS_RGB(255, 255, 255)) = 0;

	/**
	 * Creates a screenshot of the current frame buffer and writes it to a graphic file in PNG format.
	 * Returns true if the screenshot was saved successfully.
	 * Notes: This method should only be called after a call to EndFrame(), and before the next call to StartFrame().
	 * @param Filename  The filename for the screenshot
	 */
	bool SaveScreenshot(const Common::String &Filename);

	/**
	 * Creates a thumbnail with the dimensions of 200x125. This will not include the top and bottom of the screen..
	 * the interface boards the the image as a 16th of it's original size.
	 * Notes: This method should only be called after a call to EndFrame(), and before the next call to StartFrame().
	 * The frame buffer must have a resolution of 800x600.
	 * @param Filename  The filename for the screenshot
	 */
	bool SaveThumbnailScreenshot(const Common::String &Filename);

	/**
	 * Reads the current contents of the frame buffer
	 * Notes: This method is for creating screenshots. It is not very optimised. It should only be called
	 * after a call to EndFrame(), and before the next call to StartFrame().
	 * @param Width     Returns the width of the frame buffer
	 * @param Height    Returns the height of the frame buffer
	 * @param Data      Returns the raw data of the frame buffer as an array of 32-bit colour values.
	*/
	virtual bool GetScreenshot(unsigned int &Width, unsigned int &Height, byte **Data) = 0;


	virtual RenderObjectPtr<Panel> GetMainPanel() = 0;

	/**
	 * Specifies the time (in microseconds) since the last frame has passed
	 */
	int GetLastFrameDurationMicro() {
		if (m_TimerActive) return m_LastFrameDuration;
		else return 0;
	}

	/**
	 * Specifies the time (in microseconds) the previous frame took
	*/
	float GetLastFrameDuration() {
		if (m_TimerActive) return static_cast<float>(m_LastFrameDuration) / 1000000.0f;
		else return 0;
	}

	void StopMainTimer() {
		m_TimerActive = false;
	}
	void ResumeMainTimer() {
		m_TimerActive = true;
	}
	float GetSecondaryFrameDuration() {
		return static_cast<float>(m_LastFrameDuration) / 1000000.0f;
	}

	// Accessor methods

	/**
	 * Returns the width of the output buffer in pixels
	 */
	int         GetDisplayWidth() {
		return m_Width;
	}

	/**
	 * Returns the height of the output buffer in pixels
	 */
	int         GetDisplayHeight() {
		return m_Height;
	}

	/**
	 * Returns the bounding box of the output buffer: (0, 0, Width, Height)
	 */
	BS_Rect    &GetDisplayRect() {
		return m_ScreenRect;
	}

	/**
	 * Returns the bit depth of the output buffer
	 */
	int         GetBitDepth() {
		return m_BitDepth;
	}

	/**
	 * Determines whether the frame buffer change is to be synchronised with Vsync. This is turned on by default.
	 * Notes: In windowed mode, this setting has no effect.
	 * @param Vsync     Indicates whether the frame buffer changes are to be synchronised with Vsync.
	 */
	virtual void    SetVsync(bool Vsync) = 0;

	/**
	 * Returns true if V-Sync is on.
	 * Notes: In windowed mode, this setting has no effect.
	 */
	virtual bool    GetVsync() const = 0;

	/**
	 * Returns true if the engine is running in Windowed mode.
	 */
	bool    IsWindowed() {
		return m_Windowed;
	}

	/**
	 * Fills a rectangular area of the frame buffer with a colour.
	 * Notes: It is possible to create transparent rectangles by passing a colour with an Alpha value of 255.
	 * @param FillRectPtr   Pointer to a BS_Rect, which specifies the section of the frame buffer to be filled.
	 * If the rectangle falls partly off-screen, then it is automatically trimmed.
	 * If a NULL value is passed, then the entire image is to be filled.
	 * @param Color         The 32-bit colour with which the area is to be filled. The default is BS_RGB(0, 0, 0) (black)
	    @remark Falls das Rechteck nicht völlig innerhalb des Bildschirms ist, wird es automatisch zurechtgestutzt.
	 */
	virtual bool Fill(const BS_Rect *FillRectPtr = 0, unsigned int Color = BS_RGB(0, 0, 0)) = 0;

	// Debugging Methods

	int GetFPSCount() const {
		return m_FPSCounter.GetFPS();
	}
	int GetRepaintedPixels() const {
		return m_RepaintedPixels;
	}

	Graphics::Surface _backSurface;
	Graphics::Surface *getSurface() { return &_backSurface; }

	// Access methods

	/**
	 * Returns the size of a pixel entry in bytes for a particular colour format
	 * @param ColorFormat   The desired colour format. The parameter must be of type COLOR_FORMATS
	 * @return              Returns the size of a pixel in bytes. If the colour format is unknown, -1 is returned.
	 */
	static int GetPixelSize(GraphicEngine::COLOR_FORMATS ColorFormat) {
		switch (ColorFormat) {
		case GraphicEngine::CF_RGB16:
		case GraphicEngine::CF_RGB15:
			return 2;

		case GraphicEngine::CF_RGB16_INTERLEAVED:
		case GraphicEngine::CF_RGB15_INTERLEAVED:
			return 3;

		case GraphicEngine::CF_ARGB32:
			return 4;
		default:
			return -1;
		}
	}

	/**
	 * Calculates the length of an image line in bytes, depending on a given colour format.
	 * @param ColorFormat   The colour format
	 * @param Width         The width of the line in pixels
	 * @return              Reflects the length of the line in bytes. If the colour format is
	 * unknown, -1 is returned
	 */
	static int CalcPitch(GraphicEngine::COLOR_FORMATS ColorFormat, int Width) {
		switch (ColorFormat) {
		case GraphicEngine::CF_RGB16:
		case GraphicEngine::CF_RGB15:
			return Width * 2;

		case GraphicEngine::CF_RGB16_INTERLEAVED:
		case GraphicEngine::CF_RGB15_INTERLEAVED:
			return (Width + 3) / 4 * 12;

		case GraphicEngine::CF_ARGB32:
		case GraphicEngine::CF_ABGR32:
			return Width * 4;

		default:
			BS_ASSERT(false);
		}

		return -1;
	}

	// Persistence Methods
	// -------------------
	virtual bool Persist(BS_OutputPersistenceBlock &Writer);
	virtual bool Unpersist(BS_InputPersistenceBlock &Reader);

	static void ARGBColorToLuaColor(lua_State *L, unsigned int Color);
	static unsigned int LuaColorToARGBColor(lua_State *L, int StackIndex);

protected:
	// Constructor
	// -----------
	GraphicEngine(BS_Kernel *pKernel);

	// Display Variables
	// -----------------
	int     m_Width;
	int     m_Height;
	BS_Rect m_ScreenRect;
	int     m_BitDepth;
	bool    m_Windowed;

	// Debugging Variables
	// -------------------
	Framecounter m_FPSCounter;

	unsigned int    m_RepaintedPixels;

	/**
	 * Calculates the time since the last frame beginning has passed.
	 */
	void UpdateLastFrameDuration();

private:
	bool RegisterScriptBindings();

	// LastFrameDuration Variables
	// ---------------------------
	uint64                      m_LastTimeStamp;
	unsigned int                m_LastFrameDuration;
	bool                        m_TimerActive;
	Common::Array<unsigned int> m_FrameTimeSamples;
	unsigned int                m_FrameTimeSampleSlot;
};

} // End of namespace Sword25

#endif