libnds: sprite functions and document bugs

[vuurrobin]

1. the dx parameter of the oamSetMosaic() function doesn't work (the dy parameter does work).

2. there is a function to set the mosaic for the main sprites, but there isn't a function to set the mosaic for the sub screen. I've created a function that you can copy, (modify) and paste to sprite.h. do note that the function has the same problem as oamSetMosaic() (see 1).

Code: Select all

/**
*    \brief sets sprite mosaic
*    \param dx (0-15) horizontal mosaic value
*    \param dy (0-15) horizontal mosaic value
*/
static inline void oamSetMosaicSub(unsigned int dx, unsigned int dy)
{
   sassert(dx < 16 && dy < 16, "Mosaic range is 0 to 15");

   SUB_MOSAIC_CR &= ~(0xFF00);
   SUB_MOSAIC_CR |= (dx << 8)| (dy << 12);
}

3. there aren't any functions to set the alpha blending value for the sprites, like the functions for mosaic. could you include fuctions for alpha blending?


4. with oamSet(), there is a parameter 'palette_alpha', that allows you to pass 'the alpha value for bitmap sprites (bitmap sprites must specify a value > 0 to display) [0-15]' if the sprite is in bitmap mode. I'm not sure what it is suposed to do (seeing as I could specify normal transparanty when converting the image and I thought that alpha blending applied for all sprites instead of just 1 sprite), but no matter what value I passed, nothing changed with the image.

5. currently, the oamRotateScale() funcion doesn't allow you to shear a sprite and there isn't another function to let you shear a sprite. could you include the following function people can still use it? you can modify it if you want.

Code: Select all

/**
* @brief allows you to directly sets the affine transformation matrix
*
* with this, you have more freedom to set the matrix, but it might be more difficult to use if
* you're not used to affine transformation matrix. this will erase the previous matrix stored at rotId.
*
* @param oam   the oam engine, must be &oamMain or &oamSub
* @param rotId   the id of the rotscale item you want to change, must be 0-31
* @param hdx   the horizontal x value?
* @param hdy   the horizontal y value?
* @param vdx   the vertical x value?
* @param vdy   the vertical y value?
*/
void oamAffineTransformation(OamState* oam, int rotId, int hdx, int hdy, int vdx, int vdy)
{
   sassert(rotId >= 0 && rotId < 32, "oamAffineTransformation() rotId is out of bounds, must be 0-31")   

   oam->oamRotationMemory[rotId].hdx = hdx >>12;
   oam->oamRotationMemory[rotId].hdy = hdy >>12;
   oam->oamRotationMemory[rotId].vdx = vdx >>12;
   oam->oamRotationMemory[rotId].vdy = vdy >>12;
}

documentation 'bugs':

the enums POWER_ALL_2D and POWER_ALL aren't documented in system.h.
the function videoSetMode() is doxygen documentated in video.h, but it doesn't apear in the documentation.
the function (or macro?) intToFixed() isn't documentated, as wel as de BIT() macro.
the documentation says that the return type of oamCountFragments() is void, while it actually is int.
the description of oamFreeGfx() is the same as oamGetGfxPtr(), which I dont think is right (probably a copy paste mistake).
the description of oamSetMosaic() says 'sets sprite mosaic', which makes you think that is't sprite specific. could you change it so it says that the effect go's for every sprite that has mosaic turned on.
lcdMainOnBottom(), lcdMainOnTop() and lcdSwap() aren't in the documentation.
the documentation of the VideoMode enum seems off (the comments aren't with the correct enum value). it seems correct in the code, so this may be fixed with just updating the docs.

and you don't need to specify the function if the function follows directly after the doxygen comment.

I'm pretty sure there are some other functions/macro's that aren't documented.


greets

vuurrobin