DSOL::Sprites::Sprite Class Reference

a class for working with ds sprites. More...

#include <Sprite.hpp>

Inherits DSOL::IUpdate.

List of all members.

Public Member Functions

SpriteallocateAffineMatrix ()
 allocates a new affine matrix, if the sprite doesn't own a matrix already.
SpriteallocateGraphics ()
 allocates vram for the sprite, if it doesn't already owns vram.
SpriteallocatePalette ()
 allocates a palette index, if the sprite doesn't own a palette index already.
const AffineMatrixgetAffineMatrixPointer () const
 the constant version of getRotateScalePointer(), usable with constant objects.
AffineMatrixgetAffineMatrixPointer ()
 returns a pointer to a SpriteRotateScale object.
const SpriteColorFormat getColorFormat () const
 returns the color format of the sprite.
const uint getCurrentFrame () const
 returns the current frame the sprite is on.
const bool getDoubleSizeOnRotation () const
 returns if the sprites size is doubled when the sprite is rotated.
const u16 * getGfxPointer () const
 the constant version of getGfxPointer(), usable with constant objects.
u16 * getGfxPointer ()
 returns a pointer to where the graphics of the sprite is located.
const uint getHeight () const
 returns the height of the sprite.
const int getIndex () const
 returns the index of the sprite.
const uint getMaxNumberOfFrames () const
 returns the number of frames the sprite has.
const bool getPaletteIndexOrAlphaValue () const
 returns the sprites palette index or the alpha value.
const uint getPriority () const
 returns the priority of the sprite.
const SpriteSize getSize () const
 returns the size of the sprite.
const uint getWidth () const
 returns the width of the sprite.
const int getXPos () const
 returns the x position of the sprite.
const int getYPos () const
 returns the y position of the sprite.
const bool isHorizontalFlipped () const
 returns the sprites horizontally flipped.
const bool isMosaic () const
 returns if the sprite apply's mosaic is applied.
const bool isOnMainEngine () const
 returns if the sprite uses the main oam or not.
const bool isVerticalFlipped () const
 returns the sprites vertically flipped.
const bool isVisible () const
 returns the sprites visibility.
const Spriteoperator= (const Sprite &source)
 the asigment operator, copies the data from 1 Sprite to the other.
SpritesetAffineMatrixPointer (AffineMatrix *affineMatrixPointer=NULL)
 sets a pointer to a AffineMatrix object.
SpritesetDoubleSizeOnRotation (const bool doubleSizeOnRotation=false)
 sets if the sprites size should be doubled when the sprite is rotated.
virtual SpritesetFrame (const uint newFrame=0)
 sets a new frame to the sprite, must be between 0 and (maxFrame-1).
SpritesetGfxPointer (u16 *gfxPointer)
 sets a pointer to the graphics.
SpritesetHorizontalFlip (const bool flipHorizontal=false)
 sets the sprites horizontal flip.
SpritesetIndex (const uint index)
 sets the index of the sprite.
SpritesetMosaic (const bool mosaic=false)
 sets the sprites mosaic.
SpritesetPaletteIndexOrAlphaValue (const int paletteIndexOrAlphaValue)
 sets the sprites palette index or the alpha value.
SpritesetPosition (const int xPos=0, const int yPos=0)
 sets the x and y position of the sprite.
SpritesetPriority (const uint priority=0)
 sets the priority of the sprite.
SpritesetVerticalFlip (const bool flipVertical=false)
 sets the sprites vertical flip.
SpritesetVisible (const bool visible=true)
 sets the sprites visibility.
SpritesetXPos (const int xPos=0)
 sets the x position of the sprite.
SpritesetYPos (const int yPos=0)
 sets the y position of the sprite.
 Sprite (const Sprite &source, const bool takeOwnership=true)
 the Copy constructor, copies the data from 1 Sprite to the other.
 Sprite (const uint index, const SpriteSize size, const SpriteColorFormat colorFormat, u16 *gfxPointer, const uint paletteIndexOrAlphaValue, const bool useMainOam=true, AffineMatrix *affineMatrixPointer=NULL)
 The second sprite constuctor, which doesn't allocate vram or copies data.
 Sprite (const uint index, const u32 *dataPointer, const uint dataLength, const u16 *palettePointer, const uint paletteLength, const SpriteSize size, const SpriteColorFormat colorFormat, const bool useMainOam=true, const bool useAffineMatrix=false)
 The first sprite constructor, which will allocate everything itself (vram, palette, affine matrix, ect).
virtual Spriteupdate ()
 updates the sprite info to the oam 'shadow memory'.
SpritewriteGraphics (const u32 *dataPointer, const uint dataLength)
 writes data directly to the Sprites vram.
SpritewritePalette (const u16 *dataPointer, const uint dataLength)
 writes to the palette of the Sprite.
virtual ~Sprite ()
 the deconstructor, it makes the sprite invisible and releases stuff.

Static Public Attributes

static const uint NUMBER_OF_PRIORITIES = 4
 a constant for the number of priorities that exists.
static const uint NUMBER_OF_SPRITES = 128
 a constant for the number of sprites thats available per engine.

Protected Member Functions

void releaseAffineMatrix ()
 releases the affine matrix if the sprite owns one.
void releaseGFX ()
 releases the graphics pointer if the sprite owns one.
void releasePalette ()
 releases the palette if the sprite owns one.
 Sprite (const Sprite &source, const bool allocateNew, const bool takeOwnership, const uint unused=0)
 the 'reconstruct' constructor, recreates an already created object.
 Sprite (const uint index, const SpriteSize size, const SpriteColorFormat colorFormat, u16 *gfxPointer, const uint paletteIndexOrAlphaValue, const bool useMainOam, AffineMatrix *affineMatrixPointer, const uint maxNumberOfFrames, const uint currentFrame)
 an alternative version of the second sprite constuctor.

Protected Attributes

uint currentFrame
 the frame the image currently is on.
uint maxNumberOfFrames
 the number of frames the image has.


Detailed Description

a class for working with ds sprites.

this class has 2 constructors. the first one will allocate vram, palette index, ect itself, which makes it very easy to work with. the second constructor requires a bit more work (like allocating vram yourself), but it is more flexible (like allowing you to choose how to allocate vram). be very carefull with asigning sprites and vram ownership, so you won't get sprites with invalid vram.


Constructor & Destructor Documentation

DSOL::Sprites::Sprite::Sprite ( const uint  index,
const SpriteSize  size,
const SpriteColorFormat  colorFormat,
u16 *  gfxPointer,
const uint  paletteIndexOrAlphaValue,
const bool  useMainOam,
AffineMatrix affineMatrixPointer,
const uint  maxNumberOfFrames,
const uint  currentFrame 
) [inline, protected]

an alternative version of the second sprite constuctor.

with this protected constructor, you can set the protected variables maxNumberOfFrames and currentFrame.

Parameters:
index the index into the oam (0-127), must be unique for every sprite in an engine.
size the size of the sprite, as an SpriteSize enum defined in libnds.
colorFormat the number of bits that a pixel uses, as an libnds enum variable.
gfxPointer a pointer to the graphics data.
paletteIndexOrAlphaValue the palette index, or the alpha value if ColorFormat is bmp.
useMainOam true if the sprite should be on the main engine, false for the sub engine.
affineMatrixPointer a pointer to a AffineMatrix class that holds the Matrix.
maxNumberOfFrames a value for maxNumberOfFrames. not used by this constructor, so usable by any derived class.
currentFrame a value for currentFrame. not used by this constructor, so usable by any derived class.

DSOL::Sprites::Sprite::Sprite ( const Sprite source,
const bool  allocateNew,
const bool  takeOwnership,
const uint  unused = 0 
) [protected]

the 'reconstruct' constructor, recreates an already created object.

the reconstruct constructor will destruct the current object and copy all the data from source, like the copy constructor. you can specify if the sprite should allocate new vram, palette, ect or should use the sources vram, palette ect. this constructor is (almost) exclusively for operator=.

Parameters:
source the source to copy from.
allocateNew true if the sprite should allocate new vram ect, false if it should just share the sources vram, ect.
takeOwnership true if the sprite should take ownership, false for not. ignored if allocateNew is true.
unused an unused parameter so the compiler knows the difference between the copy constructor and the reconstruct constructor. unneeded here, but kept for consistency.

DSOL::Sprites::Sprite::Sprite ( const uint  index,
const u32 *  dataPointer,
const uint  dataLength,
const u16 *  palettePointer,
const uint  paletteLength,
const SpriteSize  size,
const SpriteColorFormat  colorFormat,
const bool  useMainOam = true,
const bool  useAffineMatrix = false 
)

The first sprite constructor, which will allocate everything itself (vram, palette, affine matrix, ect).

Sprites constructor 1, will allocate vram, palette ect and also copy graphics, palette ect. This is the easiest way to create a sprite, and should be enough most of the time. The constuctor will create a sprite with the given information, but it will not update it. After creating the sprite, you should change the information you want, and then update the sprite yourself with the update function. This system also allows you to set the frame of the sprite, because the sprite knows all the frames.

Parameters:
index the index into the oam (0-127), must be unique for every sprite in an engine.
dataPointer a pointer to the graphics data.
dataLength the length of the graphics data.
palettePointer a pointer to the palette data. if NULL, palette wont be copied, and user has to specify which palette to use with paletteLength. ignored if ColorFormat is bmp.
paletteLength the lenght of the palette data, or the palette index if palettePointer is NULL, or the alpha value if ColorFormat is bmp.
size the size of the sprite, as an libnds SpriteSize enum value.
colorFormat the number of bits that a pixel uses, as an libnds SpriteColorFormat enum value.
useMainOam true if the sprite is for the main engine, false otherwise. default is true.
useAffineMatrix true if the sprite needs an affine matrix, false otherwise. default is false.

DSOL::Sprites::Sprite::Sprite ( const uint  index,
const SpriteSize  size,
const SpriteColorFormat  colorFormat,
u16 *  gfxPointer,
const uint  paletteIndexOrAlphaValue,
const bool  useMainOam = true,
AffineMatrix affineMatrixPointer = NULL 
) [inline]

The second sprite constuctor, which doesn't allocate vram or copies data.

Sprites constructor 2, doesn't allocate vram, palette ect and also doesn't copy graphics, palette ect. You have to do alot more this way, but you will have more freedom doing it. Do make sure that it doesn't conflict with the library system. The constuctor will create a sprite with the given information, but it will not update it. After creating the sprite, you should change the information you want, and then update the sprite yourself with the update function. This system doesn't allows you to set the frame of the sprite, because the sprite doesn't knows all the frames. the maximum number of frames is always 1 and the current frame is always 0.

Parameters:
index the index into the oam (0-127), must be unique for every sprite in an engine.
size the size of the sprite, as an SpriteSize enum defined in libnds.
colorFormat the number of bits that a pixel uses, as an libnds enum variable.
gfxPointer a pointer to the graphics data.
paletteIndexOrAlphaValue the palette index, or the alpha value if ColorFormat is bmp.
useMainOam true if the sprite should be on the main engine, false for the sub engine. default is true.
affineMatrixPointer a pointer to an AffineMatrix object that holds the Matrix. default is NULL.

DSOL::Sprites::Sprite::Sprite ( const Sprite source,
const bool  takeOwnership = true 
)

the Copy constructor, copies the data from 1 Sprite to the other.

the copy constructor won't allocate vram, palette ect itself, but uses the sources stuff. it will also take ownership of the vram ect by default (so you can use it correctly with std::vector or LiteVector).

Parameters:
source the source sprite to copy from.
takeOwnership true if the sprite should take ownership of the vram ect, false if the source should keep ownership. default is true.

virtual DSOL::Sprites::Sprite::~Sprite (  )  [virtual]

the deconstructor, it makes the sprite invisible and releases stuff.

this deconstructor will hide the sprite, and it will also release the graphics, palettes and affine matrix it owns.


Member Function Documentation

Sprite& DSOL::Sprites::Sprite::allocateAffineMatrix (  ) 

allocates a new affine matrix, if the sprite doesn't own a matrix already.

with this function, you can let the sprite allocate a matrix, just like the sprite would have done if you passed true to the affine matrix parameter of the first constructor. you can always use this function, even if you used the second constructor.

Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::allocateGraphics (  ) 

allocates vram for the sprite, if it doesn't already owns vram.

with this function, you can let the sprite allocate vram, just like the first constructor would have done. however, it doesn't copy data to it, so you should copy the data yourself, or else there will be garbage on the screen.

you can always use this function, even if you used the second constructor. however, if you're planning to use this, then you should try to just let the first constructor handle it.

Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::allocatePalette (  ) 

allocates a palette index, if the sprite doesn't own a palette index already.

with this function, you can let the sprite allocate a palette index, just like the first constructor would have done. however, it won't copy data to the palette, so you should copy the data to the palette yourself, or else the sprite will have random colors.

you can always use this function, even if you used the second constructor. however, if you're planning to use this, then you should try to just let the first constructor handle it.

Returns:
a reference to the object, so you can chain multiple commands.

const AffineMatrix* DSOL::Sprites::Sprite::getAffineMatrixPointer (  )  const [inline]

the constant version of getRotateScalePointer(), usable with constant objects.

Returns:
a const pointer to where the graphics of the sprite is located.

AffineMatrix* DSOL::Sprites::Sprite::getAffineMatrixPointer (  )  [inline]

returns a pointer to a SpriteRotateScale object.

this will return a pointer to the SpriteRotateScale object being used, or 'NULL' if the sprite doesn't have a SpriteRotateScale object, and thus isn't rotated or scaled.

Returns:
a pointer to where the graphics of the sprite is located.

const SpriteColorFormat DSOL::Sprites::Sprite::getColorFormat (  )  const [inline]

returns the color format of the sprite.

Returns:
the color format of the sprite, as an libnds enum value.

const uint DSOL::Sprites::Sprite::getCurrentFrame (  )  const [inline]

returns the current frame the sprite is on.

this will return 1 if you didn't provide the frame data with the constructor (if you used the second constructor).

Returns:
the current frame the sprite is on.

const bool DSOL::Sprites::Sprite::getDoubleSizeOnRotation (  )  const [inline]

returns if the sprites size is doubled when the sprite is rotated.

Returns:
true if the sprites size is doubled when the sprite is rotated, false otherwise.

const u16* DSOL::Sprites::Sprite::getGfxPointer (  )  const [inline]

the constant version of getGfxPointer(), usable with constant objects.

Returns:
a const pointer to where the graphics of the sprite is located.

u16* DSOL::Sprites::Sprite::getGfxPointer (  )  [inline]

returns a pointer to where the graphics of the sprite is located.

Returns:
a pointer to where the graphics of the sprite is located.

const uint DSOL::Sprites::Sprite::getHeight (  )  const [inline]

returns the height of the sprite.

Returns:
the width of the sprite.

const int DSOL::Sprites::Sprite::getIndex (  )  const [inline]

returns the index of the sprite.

Returns:
the index of the sprite.

const uint DSOL::Sprites::Sprite::getMaxNumberOfFrames (  )  const [inline]

returns the number of frames the sprite has.

this will return 1 if you didn't provide the frame data with the constructor (if you used the second constructor).

Returns:
the number of framse the sprite has.

const bool DSOL::Sprites::Sprite::getPaletteIndexOrAlphaValue (  )  const [inline]

returns the sprites palette index or the alpha value.

returns the sprites palette index if the sprite uses extended palletes or the alpha value for bitmap sprites.

Returns:
true if the sprites size is doubled when the sprite is rotated, false otherwise.

const uint DSOL::Sprites::Sprite::getPriority (  )  const [inline]

returns the priority of the sprite.

Returns:
the priority of the sprite (0-3).

const SpriteSize DSOL::Sprites::Sprite::getSize (  )  const [inline]

returns the size of the sprite.

Returns:
the size of the sprite, as an libnds enum value.

const uint DSOL::Sprites::Sprite::getWidth (  )  const [inline]

returns the width of the sprite.

Returns:
the width of the sprite.

const int DSOL::Sprites::Sprite::getXPos (  )  const [inline]

returns the x position of the sprite.

Returns:
the x position of the sprite.

const int DSOL::Sprites::Sprite::getYPos (  )  const [inline]

returns the y position of the sprite.

Returns:
the y position of the sprite.

const bool DSOL::Sprites::Sprite::isHorizontalFlipped (  )  const [inline]

returns the sprites horizontally flipped.

Returns:
true if the sprite is horizontally flipped, false otherwise.

const bool DSOL::Sprites::Sprite::isMosaic (  )  const [inline]

returns if the sprite apply's mosaic is applied.

Returns:
true if a mosaic is applyed to the sprite, false otherwise.

const bool DSOL::Sprites::Sprite::isOnMainEngine (  )  const [inline]

returns if the sprite uses the main oam or not.

Returns:
true if it uses the main oam, false otherwise.

const bool DSOL::Sprites::Sprite::isVerticalFlipped (  )  const [inline]

returns the sprites vertically flipped.

Returns:
true if the sprite is vertically flipped, false otherwise.

const bool DSOL::Sprites::Sprite::isVisible (  )  const [inline]

returns the sprites visibility.

Returns:
true if the sprite is visible, false otherwise.

const Sprite& DSOL::Sprites::Sprite::operator= ( const Sprite source  )  [inline]

the asigment operator, copies the data from 1 Sprite to the other.

the copy constructor won't allocate vram, palette ect itself, but uses the sources stuff. it will also take ownership of the vram ect (so you can use it correctly with std::vector or LiteVector).

Parameters:
source the source to copy from.
Returns:
a reference to the object, so you can chain multiple commands (including asignments).

void DSOL::Sprites::Sprite::releaseAffineMatrix (  )  [protected]

releases the affine matrix if the sprite owns one.

void DSOL::Sprites::Sprite::releaseGFX (  )  [protected]

releases the graphics pointer if the sprite owns one.

void DSOL::Sprites::Sprite::releasePalette (  )  [protected]

releases the palette if the sprite owns one.

Sprite& DSOL::Sprites::Sprite::setAffineMatrixPointer ( AffineMatrix affineMatrixPointer = NULL  )  [inline]

sets a pointer to a AffineMatrix object.

sets a pointer to a AffineMatrix object, which hold the data for affine transformation (rotating, scaling, ect). seeing as there can be only a limited amount of AffineMatrix objects (32, a hardware limitation). you can use this to let multiple sprites use the same AffineMatrix object. if the sprite doesn't need affine transformation, you can set this to NULL.

Parameters:
affineMatrixPointer a pointer to an AffineMatrix object, default is NULL.
Returns:
a reference to the sprite object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setDoubleSizeOnRotation ( const bool  doubleSizeOnRotation = false  )  [inline]

sets if the sprites size should be doubled when the sprite is rotated.

Parameters:
doubleSizeOnRotation true if the sprites size should be doubled when the sprite is rotated, false otherwise. default is false.
Returns:
a reference to the object, so you can chain multiple commands.

virtual Sprite& DSOL::Sprites::Sprite::setFrame ( const uint  newFrame = 0  )  [virtual]

sets a new frame to the sprite, must be between 0 and (maxFrame-1).

this will not work if you didn't provide the frame data with the constructor (if you used the second constructor). it will display an error message in debug mode. it will write the data directly, so there may be a glitch if you used it wrongly (during the drawing of the sprites to the screen).

Parameters:
newFrame the new frame of the sprite, default is 0.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setGfxPointer ( u16 *  gfxPointer  )  [inline]

sets a pointer to the graphics.

sets a pointer to where the graphics of the sprite is located.

Parameters:
gfxPointer a pointer to the graphics of the sprite.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setHorizontalFlip ( const bool  flipHorizontal = false  )  [inline]

sets the sprites horizontal flip.

Parameters:
flipHorizontal true if the sprite should be horizontally flipped, false if it shouldn't be flipped. default is false.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setIndex ( const uint  index  )  [inline]

sets the index of the sprite.

Parameters:
index the new index of the sprite.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setMosaic ( const bool  mosaic = false  )  [inline]

sets the sprites mosaic.

Parameters:
mosaic true if it should apply mosaic, false otherwise. default is false.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setPaletteIndexOrAlphaValue ( const int  paletteIndexOrAlphaValue  )  [inline]

sets the sprites palette index or the alpha value.

Parameters:
paletteIndexOrAlphaValue the palette index if the sprite uses palettes, or the alpha value for bitmap sprites.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setPosition ( const int  xPos = 0,
const int  yPos = 0 
) [inline]

sets the x and y position of the sprite.

Parameters:
xPos the x position of the sprite, default is 0.
yPos the y position of the sprite, default is 0.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setPriority ( const uint  priority = 0  )  [inline]

sets the priority of the sprite.

sets the priority of the sprite. the lower the priority, the later it is drawed, the more on top it is.

Parameters:
priority the priority of the sprite (0-3), default is 0.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setVerticalFlip ( const bool  flipVertical = false  )  [inline]

sets the sprites vertical flip.

Parameters:
flipVertical true if the sprite should be vertically flipped, false if it shouldn't be flipped. default is false.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setVisible ( const bool  visible = true  )  [inline]

sets the sprites visibility.

Parameters:
visible true if the sprite should be visible, false if it should be hidden. default is true.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setXPos ( const int  xPos = 0  )  [inline]

sets the x position of the sprite.

Parameters:
xPos the x position of the sprite, default is 0.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::setYPos ( const int  yPos = 0  )  [inline]

sets the y position of the sprite.

Parameters:
yPos the y position of the sprite, default is 0.
Returns:
a reference to the object, so you can chain multiple commands.

virtual Sprite& DSOL::Sprites::Sprite::update (  )  [inline, virtual]

updates the sprite info to the oam 'shadow memory'.

this will update the sprite info to the oam 'shadow memory' (the shadow memory is actually created by libnds). you will still need to update the oam itself during vblank (will be done in the vblank() function of this library).

Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::writeGraphics ( const u32 *  dataPointer,
const uint  dataLength 
) [inline]

writes data directly to the Sprites vram.

this can be used with the second constructor to overwrite the sprite, or the first constructor if you didn't provide the data with the constructor (it is recommanded to pass all the data with the first constructor).

Parameters:
dataPointer a pointer to the graphics data.
dataLength the length of the data in bytes.
Returns:
a reference to the object, so you can chain multiple commands.

Sprite& DSOL::Sprites::Sprite::writePalette ( const u16 *  dataPointer,
const uint  dataLength 
) [inline]

writes to the palette of the Sprite.

this can be used to overwrite the palette.

Parameters:
dataPointer a pointer to the palette data.
dataLength the length of the data in bytes.
Returns:
a reference to the object, so you can chain multiple commands.


Member Data Documentation

the frame the image currently is on.

a protected member that you can use in your derived classes. this is used when using the first constructor, so make sure not to change it unless you use the second constructor.

the number of frames the image has.

a protected member that you can use in your derived classes. this is used when using the first constructor, so make sure not to change it unless you use the second constructor.

a constant for the number of priorities that exists.

const uint DSOL::Sprites::Sprite::NUMBER_OF_SPRITES = 128 [static]

a constant for the number of sprites thats available per engine.


The documentation for this class was generated from the following file:

Generated on Thu Sep 10 19:09:48 2009 for DSOL by  doxygen 1.5.8