Introduction

A rendering engine is responsible for all low-level rendering tasks in CorsixTH. Its most important roles are:

1. Creating a canvas to render onto (typically a window).
2. Loading Theme Hospital sprite sheets.
3. 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.

Built-in rendering engines

At the moment, CorsixTH has a number of rendering engines. The engine is chosen at compile time by defining the appropriate flag in config.h.

The AnimView tool uses its own rendering engine rather than one of the above. The AnimView rendering engine is used for research purposes, and renders onto a wxImage. It has a different C++ API to the above engines, and no Lua API.

C++ 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

Lua API

TODO