diff --git a/Source/engine.cpp b/Source/engine.cpp index e45e487c9..5836aafa6 100644 --- a/Source/engine.cpp +++ b/Source/engine.cpp @@ -26,6 +26,12 @@ const int RndInc = 1; */ const int RndMult = 0x015A4E35; +/** + * @brief Find the start of a CEL frame + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nDataSize Will be set to frame size + */ __FINLINE BYTE *CelGetFrame(BYTE *pCelBuff, int nCel, int *nDataSize) { DWORD *pFrameTable; @@ -38,6 +44,12 @@ __FINLINE BYTE *CelGetFrame(BYTE *pCelBuff, int nCel, int *nDataSize) return pCelBuff + nCellStart; } +/** + * @brief Calculate the size of a CEL frame + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @return Size of CEL in bytes + */ __FINLINE int CelGetFrameSize(BYTE *pCelBuff, int nCel) { DWORD *pFrameTable; @@ -47,6 +59,13 @@ __FINLINE int CelGetFrameSize(BYTE *pCelBuff, int nCel) return SwapLE32(pFrameTable[nCel + 1]) - SwapLE32(pFrameTable[nCel]); } +/** + * @brief Blit CEL sprite to the given buffer + * @param pDecodeTo The output buffer + * @param pRLEBytes CEL pixel stream (run-length encoded) + * @param nDataSize Size of CEL in bytes + * @param nWidth Width of sprite + */ void CelBlit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) { int w; @@ -146,6 +165,14 @@ void CelBlit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) #endif } +/** + * @brief Blit CEL sprite to the back buffer at the given coordinates + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite + */ void CelDraw(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth) { int nDataSize; @@ -162,6 +189,13 @@ void CelDraw(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth) CelBlit(&gpBuffer[sx + PitchTbl[sy]], pRLEBytes, nDataSize, nWidth); } +/** + * @brief Blit a given CEL frame to the given buffer + * @param pBuff Target buffer + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite + */ void CelBlitFrame(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth) { int nDataSize; @@ -179,6 +213,12 @@ void CelBlitFrame(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth) } /** + * @brief Same as CelDraw but with the option to skip parts of the top and bottom of the sprite + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -220,6 +260,11 @@ void CelClippedDraw(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int Ce } /** + * @brief Same as CelBlit but with the option to skip parts of the top and bottom of the sprite + * @param pBuff Target buffer + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -256,6 +301,13 @@ void CelClippedBlit(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth, int CelSk CelBlit(pBuff, pRLEBytes + nDataStart, nDataSize, nWidth); } +/** + * @brief Blit CEL sprite, and apply lighting, to the given buffer + * @param pDecodeTo The output buffer + * @param pRLEBytes CEL pixel stream (run-length encoded) + * @param nDataSize Size of CEL in bytes + * @param nWidth Width of sprite + */ void CelBlitLight(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) { int w; @@ -409,6 +461,13 @@ void CelBlitLight(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) #endif } +/** + * @brief Blit CEL sprite, and apply lighting, to the given buffer, with transparancy applied + * @param pDecodeTo The output buffer + * @param pRLEBytes CEL pixel stream (run-length encoded) + * @param nDataSize Size of CEL in bytes + * @param nWidth Width of sprite + */ void CelBlitLightTrans(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) { int w; @@ -596,6 +655,14 @@ void CelBlitLightTrans(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWid #endif } +/** + * @brief Blit CEL sprite, and apply lighting, to the back buffer at the given coordinates + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite + */ void CelDrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth) { int nDataSize; @@ -618,6 +685,12 @@ void CelDrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth) } /** + * @brief Same as CelDrawLight but with the option to skip parts of the top and bottom of the sprite + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -661,6 +734,11 @@ void CelClippedDrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, i } /** + * @brief Same as CelBlitLightTrans but with the option to skip parts of the top and bottom of the sprite + * @param pBuff Target buffer + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -705,8 +783,15 @@ void CelClippedBlitLightTrans(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth, } /** + * @brief Blit CEL sprite, and apply lighting, to the back buffer at the given coordinates, translated to a red hue + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 + * @param light Light shade to use */ void CelDrawLightRed(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSkip, int CelCap, char light) { @@ -823,6 +908,10 @@ void CelDrawLightRed(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int C /** * @brief Same as CelBlit but checks for drawing outside the buffer + * @param pDecodeTo The output buffer + * @param pRLEBytes CEL pixel stream (run-length encoded) + * @param nDataSize Size of CEL in bytes + * @param nWidth Width of sprite */ void CelBlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) { @@ -938,6 +1027,12 @@ void CelBlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) } /** + * @brief Same as CelClippedDraw but checks for drawing outside the buffer + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -979,6 +1074,11 @@ void CelClippedDrawSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, in } /** + * @brief Same as CelClippedBlit but checks for drawing outside the buffer + * @param pBuff Target buffer + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -1017,6 +1117,10 @@ void CelClippedBlitSafe(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWidth, int C /** * @brief Same as CelBlitLight but checks for drawing outside the buffer + * @param pDecodeTo The output buffer + * @param pRLEBytes CEL pixel stream (run-length encoded) + * @param nDataSize Size of CEL in bytes + * @param nWidth Width of sprite */ void CelBlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) { @@ -1188,6 +1292,10 @@ void CelBlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidt /** * @brief Same as CelBlitLightTrans but checks for drawing outside the buffer + * @param pDecodeTo The output buffer + * @param pRLEBytes CEL pixel stream (run-length encoded) + * @param nDataSize Size of CEL in bytes + * @param nWidth Width of sprite */ void CelBlitLightTransSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) { @@ -1391,6 +1499,12 @@ void CelBlitLightTransSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int } /** + * @brief Same as CelDrawLight but checks for drawing outside the buffer + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of cel * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -1434,6 +1548,11 @@ void CelDrawLightSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int } /** + * @brief Same as CelClippedBlitLightTrans but checks for drawing outside the buffer + * @param pBuff Target buffer + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of cel * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -1476,8 +1595,14 @@ void CelClippedBlitLightTransSafe(BYTE *pBuff, BYTE *pCelBuff, int nCel, int nWi /** * @brief Same as CelDrawLightRed but checks for drawing outside the buffer + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff Cel data + * @param nCel CEL frame number + * @param nWidth Width of cel * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 + * @param light Light shade to use */ void CelDrawLightRedSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSkip, int CelCap, char light) { @@ -1607,7 +1732,7 @@ void CelDrawLightRedSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, i * @param y Cordinate in pBuff buffer * @param wdt Width of pBuff * @param pCelBuff Cel data - * @param nCel Frame of cel + * @param nCel CEL frame number * @param nWidth Width of cel */ void CelBlitWidth(BYTE *pBuff, int x, int y, int wdt, BYTE *pCelBuff, int nCel, int nWidth) @@ -1725,6 +1850,13 @@ void CelBlitWidth(BYTE *pBuff, int x, int y, int wdt, BYTE *pCelBuff, int nCel, } /** + * @brief Blit a solid colder shape one pixel larger then the given sprite shape, to the back buffer at the given coordianates + * @param col Color index from current palette + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff CEL buffer + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -1867,6 +1999,12 @@ void CelBlitOutline(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int nWid /** * @brief Same as CelBlitOutline but checks for drawing outside the buffer + * @param col Color index from current palette + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param pCelBuff CEL buffer + * @param nCel CEL frame number + * @param nWidth Width of sprite * @param CelSkip Skip lower parts of sprite, must be multiple of 2, max 8 * @param CelCap Amount of sprite to render from lower to upper, must be multiple of 2, max 8 */ @@ -2049,6 +2187,12 @@ void CelBlitOutlineSafe(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int #endif } +/** + * @brief Set the value of a single pixel in the back buffer, checks bounds + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + * @param col Color index from current palette + */ void ENG_set_pixel(int sx, int sy, BYTE col) { BYTE *dst; @@ -2075,6 +2219,11 @@ void ENG_set_pixel(int sx, int sy, BYTE col) #endif } +/** + * @brief Set the value of a single pixel in the back buffer to that of gbPixelCol, checks bounds + * @param sx Back buffer coordinate + * @param sy Back buffer coordinate + */ void engine_draw_pixel(int sx, int sy) { BYTE *dst; @@ -2106,18 +2255,6 @@ void engine_draw_pixel(int sx, int sy) #endif } -// Exact copy from https://github.com/erich666/GraphicsGems/blob/dad26f941e12c8bf1f96ea21c1c04cd2206ae7c9/gems/DoubleLine.c -// Except: -// * not in view checks -// * global variable instead of reverse flag -// * condition for pixels_left < 0 removed - -/* -Symmetric Double Step Line Algorithm -by Brian Wyvill -from "Graphics Gems", Academic Press, 1990 -*/ - #define GG_SWAP(A, B) \ { \ (A) ^= (B); \ @@ -2126,6 +2263,24 @@ from "Graphics Gems", Academic Press, 1990 } #define GG_ABSOLUTE(I, J, K) (((I) - (J)) * ((K) = (((I) - (J)) < 0 ? -1 : 1))) +/** + * Symmetric Double Step Line Algorithm + * by Brian Wyvill + * from "Graphics Gems", Academic Press, 1990 + * + * Exact copy from https://github.com/erich666/GraphicsGems/blob/dad26f941e12c8bf1f96ea21c1c04cd2206ae7c9/gems/DoubleLine.c + * Except: + * - not in view checks + * - global variable instead of reverse flag + * - condition for pixels_left < 0 removed + * + * @brief Draw a line on the back buffer + * @param x0 Back buffer coordinate + * @param y0 Back buffer coordinate + * @param x1 Back buffer coordinate + * @param y1 Back buffer coordinate + * @param col Color index from current palette + */ void DrawLine(int x0, int y0, int x1, int y1, BYTE col) { int dx, dy, incr1, incr2, D, x, y, xend, c, pixels_left; @@ -2315,6 +2470,14 @@ void DrawLine(int x0, int y0, int x1, int y1, BYTE col) } } +/** + * @brief Calculate the best fit direction between two points + * @param x1 Tile coordinate + * @param y1 Tile coordinate + * @param x2 Tile coordinate + * @param y2 Tile coordinate + * @return A value from the direction enum + */ int GetDirection(int x1, int y1, int x2, int y2) { int mx, my; @@ -2356,6 +2519,10 @@ int GetDirection(int x1, int y1, int x2, int y2) return md; } +/** + * @brief Set the RNG seed + * @param s RNG seed + */ void SetRndSeed(int s) { SeedCount = 0; @@ -2363,6 +2530,10 @@ void SetRndSeed(int s) orgseed = s; } +/** + * @brief Get the current RNG seed + * @return RNG seed + */ int GetRndSeed() { SeedCount++; @@ -2370,6 +2541,12 @@ int GetRndSeed() return abs(sglGameSeed); } +/** + * @brief Main RNG function + * @param idx Unused + * @param v The upper limit for the return value + * @return A random number from 0 to (v-1) + */ int random_(BYTE idx, int v) { if (v <= 0) @@ -2394,6 +2571,10 @@ void engine_debug_trap(BOOL show_cursor) */ } +/** + * @brief Multithreaded safe malloc + * @param dwBytes Byte size to allocate + */ BYTE *DiabloAllocPtr(DWORD dwBytes) { BYTE *buf; @@ -2413,6 +2594,10 @@ BYTE *DiabloAllocPtr(DWORD dwBytes) return buf; } +/** + * @brief Multithreaded safe memfree + * @param p Memory pointer to free + */ void mem_free_dbg(void *p) { if (p) { @@ -2426,6 +2611,12 @@ void mem_free_dbg(void *p) } } +/** + * @brief Load a file in to a buffer + * @param pszName Path of file + * @param pdwFileLen Will be set to file size if non-NULL + * @return Buffer with content of file + */ BYTE *LoadFileInMem(char *pszName, DWORD *pdwFileLen) { HANDLE file; @@ -2449,6 +2640,12 @@ BYTE *LoadFileInMem(char *pszName, DWORD *pdwFileLen) return buf; } +/** + * @brief Load a file in to the given buffer + * @param pszName Path of file + * @param p Target buffer + * @return Size of file + */ DWORD LoadFileWithMem(const char *pszName, void *p) { DWORD dwFileLen; @@ -2713,7 +2910,7 @@ void Cl2Blit(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) } /** - * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the back buffer at the given coordianates + * @brief Blit a solid colder shape one pixel larger then the given sprite shape, to the back buffer at the given coordianates * @param col Color index from current palette * @param sx Back buffer coordinate * @param sy Back buffer coordinate @@ -2762,7 +2959,7 @@ void Cl2DrawOutline(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int nWid } /** - * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the given buffer + * @brief Blit a solid colder shape one pixel larger then the given sprite shape, to the given buffer * @param pDecodeTo The output buffer * @param pRLEBytes CL2 pixel stream (run-length encoded) * @param nDataSize Size of CL2 in bytes @@ -3199,7 +3396,7 @@ void Cl2DrawLight(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelS } /** - * @brief Blit CL2 sprite to the back buffer, while checking bounds, at the given coordianates + * @brief Same as Cl2Draw but checks for drawing outside the buffer * @param sx Back buffer coordinate * @param sy Back buffer coordinate * @param pCelBuff CL2 buffer @@ -3246,7 +3443,7 @@ void Cl2DrawSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, int CelSk } /** - * @brief Blit CL2 sprite to pDecodeTo while checking bounds + * @brief Same as Cl2Blit but checks for drawing outside the buffer * @param pDecodeTo The output buffer * @param pRLEBytes CL2 pixel stream (run-length encoded) * @param nDataSize Size of CL2 in bytes @@ -3407,7 +3604,7 @@ void Cl2BlitSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidth) } /** - * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the back buffer at the given coordianates, while checking bounds + * @brief Same as Cl2DrawOutline but checks for drawing outside the buffer * @param col Color index from current palette * @param sx Back buffer coordinate * @param sy Back buffer coordinate @@ -3458,7 +3655,7 @@ void Cl2DrawOutlineSafe(char col, int sx, int sy, BYTE *pCelBuff, int nCel, int } /** - * @brief Blit a solid colder shape one pix larger then the given sprite shape, to the given buffer, while checking bounds + * @brief Same as Cl2BlitOutline but checks for drawing outside the buffer * @param pDecodeTo The output buffer * @param pRLEBytes CL2 pixel stream (run-length encoded) * @param nDataSize Size of CL2 in bytes @@ -3639,7 +3836,7 @@ void Cl2BlitOutlineSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWi } /** - * @brief Blit CL2 sprite, and apply a given lighting, to the back buffer at the given coordianates, while checking bounds + * @brief Same as Cl2DrawLightTbl but checks for drawing outside the buffer * @param sx Back buffer coordinate * @param sy Back buffer coordinate * @param pCelBuff CL2 buffer @@ -3698,7 +3895,7 @@ void Cl2DrawLightTblSafe(int sx, int sy, BYTE *pCelBuff, int nCel, int nWidth, i } /** - * @brief Blit CL2 sprite, and apply light, to pDecodeTo while checking bounds + * @brief Same as Cl2BlitLight but checks for drawing outside the buffer * @param pDecodeTo The output buffer * @param pRLEBytes CL2 pixel stream (run-length encoded) * @param nDataSize Size of CL2 in bytes @@ -3869,7 +4066,7 @@ void Cl2BlitLightSafe(BYTE *pDecodeTo, BYTE *pRLEBytes, int nDataSize, int nWidt } /** - * @brief Blit CL2 sprite, and apply lighting, to the back buffer at the given coordinates, while checking bounds + * @brief Same as Cl2DrawLight but checks for drawing outside the buffer * @param sx Back buffer coordinate * @param sy Back buffer coordinate * @param pCelBuff CL2 buffer