-
Notifications
You must be signed in to change notification settings - Fork 382
Rendering Engines
A rendering engine is responsible for all low-level rendering tasks in CorsixTH. Its most important roles are:
- Creating a canvas to render onto (typically a window).
- Loading Theme Hospital sprite sheets.
- Drawing individual sprites onto a canvas.
Higher-level constructs like fonts, maps, and animations are all built on top of sprite sheets, and are thus implemented independently from the rendering engine.
A rendering engine must provide two APIs; one for C++ code, and one for Lua code.
CorsixTH uses the SDL rendering engine. Formerly DirectX and OpenGL could be used in place of SDL. Formerly Map Editor was in a separate app using one of these rendering engines.
| Name | Notes | Define | Header | C++ API | Lua API |
|---|---|---|---|---|---|
| SDL | The "standard" rendering engine, which should work everywhere. | CORSIX_TH_USE_SDL_RENDERER |
th_gfx_sdl.h | th_gfx_sdl.cpp | sdl_video.cpp |
The AnimView tool uses wxWidgets. The AnimView rendering engine is used for research purposes, and renders onto a wxImage. It has a different C++ API to SDL, and no Lua API.
A rendering engine must define the following types:
struct THClipRect;
struct THRenderTarget;
A clip rectangle must have signed members x and y, and unsigned members w and h, though it can have others. There are no rules on the members of a THRenderTarget.
A rendering engine must provide the following two functions for manipulating the clip rectangle of a render target: void THRenderTarget_GetClipRect(const THRenderTarget* pTarget, THClipRect* pRect); void THRenderTarget_SetClipRect(THRenderTarget* pTarget, const THClipRect* pRect);
A rendering engine must provide the following two functions, though they do not have to do anything: void THRenderTarget_StartNonOverlapping(THRenderTarget* pTarget); void THRenderTarget_FinishNonOverlapping(THRenderTarget* pTarget); When in non-overlapping mode, it doesn't matter what order sprites are drawn onto the given render target. This means that the rendering engine is free to re-order draw operations into a more optimal order, though it doesn't have to.
A rendering engine must provide a {{{THPalette}}} class with at least the following members:
class THPalette
{
public:
bool loadFromTHFile(const unsigned char* pData, size_t iDataLength);
void assign(THRenderTarget* pTarget, bool bTransparent) const;
};
The loadFromTHFile method takes up to 768 bytes of data, which is composed of 1 or more RGB triplets. Each triplet is up of three bytes, each in the range 0 to 63 (not 0 to 255). The assign method is used to change the palette of a render target, though rendering engines are not required to support changing the palette of a render target after the target has been created.
The most important class which a rendering engine must provide is THSpriteSheet, which must have at least the following members:
class THSpriteSheet
{
public:
void setPalette(const THPalette* pPalette);
bool loadFromTHFile(const unsigned char* pTableData, size_t iTableDataLength,
const unsigned char* pChunkData, size_t iChunkDataLength,
bool bComplexChunks, THRenderTarget* pEventualCanvas);
void setSpriteAltPaletteMap(unsigned int iSprite, const unsigned char* pMap);
unsigned int getSpriteCount() const;
bool getSpriteSize(unsigned int iSprite, unsigned int* pX, unsigned int* pY) const;
void getSpriteSizeUnchecked(unsigned int iSprite, unsigned int* pX, unsigned int* pY) const;
void drawSprite(THRenderTarget* pCanvas, unsigned int iSprite, int iX, int iY, unsigned long iFlags);
};
TODO: Describe methods
TODO