cmdfx 0.1.1
Lightweight game engine for your terminal
All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
sprites.h File Reference

Sprites API for CmdFX. More...

Go to the source code of this file.

Classes

struct  CmdFX_Sprite
 Represents a sprite that can be drawn to the terminal. More...
 

Typedefs

typedef struct CmdFX_Sprite CmdFX_Sprite
 Represents a sprite that can be drawn to the terminal.
 

Enumerations

enum  CmdFX_GradientDirection {
  GRADIENT_HORIZONTAL , GRADIENT_HORIZONTAL_REVERSE , GRADIENT_VERTICAL , GRADIENT_VERTICAL_REVERSE ,
  GRADIENT_ANGLE_45 , GRADIENT_ANGLE_135 , GRADIENT_RADIAL , GRADIENT_CONICAL
}
 Represents a color gradient that can be applied to a sprite. More...
 

Functions

CmdFX_Sprite ** Canvas_getDrawnSprites ()
 Gets the sprites that have been drawn to the terminal.
 
int Canvas_getDrawnSpritesCount ()
 Gets the number of sprites that have been drawn to the terminal.
 
CmdFX_SpriteCanvas_getSpriteAt (int x, int y)
 Gets a sprite at the given position with the highest Z-index.
 
CmdFX_SpriteSprite_create (char **text, char ***ansi, int z)
 Creates a new sprite.
 
void Sprite_free (CmdFX_Sprite *sprite)
 Frees the memory allocated for a sprite.
 
int Sprite_draw (int x, int y, CmdFX_Sprite *sprite)
 Draws a sprite to the terminal.
 
void Sprite_remove (CmdFX_Sprite *sprite)
 Removes a sprite from the terminal, making it no longer visble.
 
int Sprite_setData (CmdFX_Sprite *sprite, char **data)
 Sets the text data for the sprite.
 
int Sprite_setChar (CmdFX_Sprite *sprite, int x, int y, char c)
 Sets the character at the given position in the sprite.
 
int Sprite_fillChar (CmdFX_Sprite *sprite, int x, int y, char c, int width, int height)
 Fills positions in the sprite.
 
int Sprite_fillCharEmpty (CmdFX_Sprite *sprite, int x, int y, char c, int width, int height)
 Fills positions in the sprite where there isn't a character.
 
int Sprite_fillCharAll (CmdFX_Sprite *sprite, char c)
 Sets the character at all positions in the sprite.
 
int Sprite_fillCharAllEmpty (CmdFX_Sprite *sprite, char c)
 Sets the character at all positions in the sprite where there isn't a character.
 
int Sprite_setAnsi (CmdFX_Sprite *sprite, int x, int y, char *ansi)
 Sets the ANSI code at the given position in the sprite.
 
int Sprite_appendAnsi (CmdFX_Sprite *sprite, int x, int y, char *ansi)
 Appends an ANSI code to the given position in the sprite.
 
int Sprite_fillAnsi (CmdFX_Sprite *sprite, int x, int y, char *ansi, int width, int height)
 Fills positions in the sprite with an ANSI code.
 
int Sprite_setAnsiAll (CmdFX_Sprite *sprite, char *ansi)
 Sets the character at all positions in the sprite.
 
int Sprite_appendAnsiAll (CmdFX_Sprite *sprite, char *ansi)
 Appends an ANSI code to all positions in the sprite.
 
CmdFX_SpriteSprite_createFilled (int width, int height, char c, char *ansi, int z)
 Creates a new sprite with the given dimensions.
 
CmdFX_SpriteSprite_loadFromFile (const char *path, int z)
 Creates a new sprite from a file.
 
int Sprite_resize (CmdFX_Sprite *sprite, int width, int height)
 Resizes the sprite to the given dimensions.
 
int Sprite_resizeWithPadding (CmdFX_Sprite *sprite, int width, int height, char padding)
 Resizes the sprite to the given dimensions.
 
int Sprite_center (CmdFX_Sprite *sprite)
 Centers the sprite on the terminal.
 
int Sprite_resizeAndCenter (CmdFX_Sprite *sprite, int width, int height)
 Resizes and centers the sprite on the terminal.
 
void Sprite_moveTo (CmdFX_Sprite *sprite, int x, int y)
 Moves a sprite to the given position.
 
void Sprite_moveBy (CmdFX_Sprite *sprite, int dx, int dy)
 Moves a sprite by the given amount.
 
CmdFX_Sprite ** Sprite_getCollidingSprites (CmdFX_Sprite *sprite)
 Gets the sprites that are colliding with the given sprite.
 
int Sprite_isColliding (CmdFX_Sprite *sprite1, CmdFX_Sprite *sprite2)
 Checks if two sprites are colliding.
 
int Sprite_isOnTop (CmdFX_Sprite *sprite, int x, int y)
 Gets whether the sprite is the top-most sprite at the given position.
 
int Sprite_isOnBottom (CmdFX_Sprite *sprite, int x, int y)
 Gets whether the sprite is the bottom-most sprite at the given position.
 
int Sprite_setForeground (CmdFX_Sprite *sprite, int x, int y, int rgb)
 Sets the foreground color of the sprite at the given position.
 
int Sprite_setForegroundAll (CmdFX_Sprite *sprite, int rgb)
 Sets the foreground color of the sprite at the given position.
 
int Sprite_setForegroundAll256 (CmdFX_Sprite *sprite, int color)
 Sets the foreground color of the sprite at the given position using 256-bit color codes.
 
int Sprite_setBackground (CmdFX_Sprite *sprite, int x, int y, int rgb)
 Sets the background color of the sprite at the given position.
 
int Sprite_setBackgroundAll (CmdFX_Sprite *sprite, int rgb)
 Sets the background color of the sprite at the given position.
 
int Sprite_setBackgroundAll256 (CmdFX_Sprite *sprite, int color)
 Sets the background color of the sprite at the given position using 256-bit color codes.
 
int Sprite_setForegroundGradient (CmdFX_Sprite *sprite, int x, int y, int width, int height, enum CmdFX_GradientDirection direction, int numColors,...)
 Sets a foreground gradient using RGB colors for a specified section of the sprite.
 
int Sprite_setForegroundGradientAll (CmdFX_Sprite *sprite, enum CmdFX_GradientDirection direction, int numColors,...)
 Sets a foreground gradient using RGB colors.
 
int Sprite_setBackgroundGradient (CmdFX_Sprite *sprite, int x, int y, int width, int height, enum CmdFX_GradientDirection direction, int numColors,...)
 Sets a background gradient using RGB colors for a specified section of the sprite.
 
int Sprite_setBackgroundGradientAll (CmdFX_Sprite *sprite, enum CmdFX_GradientDirection direction, int numColors,...)
 Sets a background gradient using RGB colors.
 
int Sprite_rotate (CmdFX_Sprite *sprite, double radians)
 Rotates the sprite by the given angle.
 
double Sprite_getRotationAngle (CmdFX_Sprite *sprite)
 Gets the rotation angle of the sprite.
 
int Sprite_hFlip (CmdFX_Sprite *sprite)
 Flips the sprite horizontally.
 
int Sprite_vFlip (CmdFX_Sprite *sprite)
 Flips the sprite vertically.
 
int Sprite_scale (CmdFX_Sprite *sprite, double scale)
 Scales the sprite by the given factor.
 
int Sprite_transpose (CmdFX_Sprite *sprite)
 Transposes the sprite.
 

Detailed Description

Sprites API for CmdFX.

Author
Gregory Mitchell (me@gm.nosp@m.itch.nosp@m.215.x.nosp@m.yz)
Version
0.1.0
Date
2025-01-21

Typedef Documentation

◆ CmdFX_Sprite

typedef struct CmdFX_Sprite CmdFX_Sprite

Represents a sprite that can be drawn to the terminal.

A sprite is a 2D image that can be drawn to the terminal. It consists of a 2D array of characters that represent the sprite, as well as a Z-index that determines the order in which sprites are drawn. Sprites are useful for keeping track of complex images or animations that need to be drawn to the terminal.

Enumeration Type Documentation

◆ CmdFX_GradientDirection

Represents a color gradient that can be applied to a sprite.

A color gradient is a smooth transition between two or more colors. The gradient can be applied to the foreground or background of a sprite, and can be applied in different directions.

Enumerator
GRADIENT_HORIZONTAL 

A horizontal gradient.

GRADIENT_HORIZONTAL_REVERSE 

A horizontal gradient in reverse.

GRADIENT_VERTICAL 

A vertical gradient.

GRADIENT_VERTICAL_REVERSE 

A vertical gradient in reverse.

GRADIENT_ANGLE_45 

A 45-degree gradient.

GRADIENT_ANGLE_135 

A 135-degree gradient.

GRADIENT_RADIAL 

A radial gradient.

GRADIENT_CONICAL 

A conical gradient.

Function Documentation

◆ Canvas_getDrawnSprites()

CmdFX_Sprite ** Canvas_getDrawnSprites ( )

Gets the sprites that have been drawn to the terminal.

This method returns an array of pointers to the sprites that have been drawn to the terminal. The array is terminated with a NULL pointer. The sprites should not be modified or freed by the caller.

Returns
An array of pointers to the drawn sprites.

◆ Canvas_getDrawnSpritesCount()

int Canvas_getDrawnSpritesCount ( )

Gets the number of sprites that have been drawn to the terminal.

Returns
The number of drawn sprites.

◆ Canvas_getSpriteAt()

CmdFX_Sprite * Canvas_getSpriteAt ( int x,
int y )

Gets a sprite at the given position with the highest Z-index.

This method returns the sprite that is drawn at the given position with the highest Z-index. If there is no sprite at the given position, the method will return NULL.

Parameters
xThe X position.
yThe Y position.
Returns
A pointer to the sprite at the given position, or NULL if no sprite is found.

◆ Sprite_appendAnsi()

int Sprite_appendAnsi ( CmdFX_Sprite * sprite,
int x,
int y,
char * ansi )

Appends an ANSI code to the given position in the sprite.

This method appends the given ANSI code to the existing ANSI code at the given position in the sprite. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
ansiThe ANSI code to append.
Returns
1 if the ANSI code was appended, 0 if the position is out of bounds or an error occurred.

◆ Sprite_appendAnsiAll()

int Sprite_appendAnsiAll ( CmdFX_Sprite * sprite,
char * ansi )

Appends an ANSI code to all positions in the sprite.

This method appends the given ANSI code to the existing ANSI code at all positions in the sprite. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
ansiThe ANSI code to append.
Returns
1 if the ANSI code was appended, 0 if the position is out of bounds or an error occurred.

◆ Sprite_center()

int Sprite_center ( CmdFX_Sprite * sprite)

Centers the sprite on the terminal.

This method centers the sprite on the terminal, both horizontally and vertically. It will reposition the data and ansi characters depending on whether there is whitespace surrounding other characters.

The sprite will be drawn at its current position.

Parameters
spriteThe sprite to center.
Returns
1 if the sprite was centered, 0 if an error occurred.

◆ Sprite_create()

CmdFX_Sprite * Sprite_create ( char ** text,
char *** ansi,
int z )

Creates a new sprite.

This method allocates memory for a new sprite and initializes it with the given parameters. The sprite should be freed with Sprite_free when it is no longer needed.

You can also set text and ansi to NULL and built them later using Sprite_setChar, Sprite_setAnsi, and Sprite_resize.

This method does not draw the sprite to the terminal. To draw the sprite, use the Sprite_draw method.

Parameters
textThe text data for the sprite.
ansiThe ANSI data for the sprite.
zThe Z-index of the sprite.
Returns
A pointer to the new sprite, or 0 if an error occurred.

◆ Sprite_createFilled()

CmdFX_Sprite * Sprite_createFilled ( int width,
int height,
char c,
char * ansi,
int z )

Creates a new sprite with the given dimensions.

This method creates a new sprite with the given dimensions. The sprite will be filled with the specified character and ANSI code. The sprite should be freed with Sprite_free when it is no longer needed.

This method does not draw the sprite to the terminal. To draw the sprite, use the Sprite_draw method.

Parameters
widthThe width of the sprite.
heightThe height of the sprite.
cThe character to fill the sprite with.
ansiThe ANSI code to fill the sprite with.
zThe Z-index of the sprite.
Returns
A pointer to the new sprite, or 0 if an error occurred.

◆ Sprite_draw()

int Sprite_draw ( int x,
int y,
CmdFX_Sprite * sprite )

Draws a sprite to the terminal.

This method draws a sprite to the terminal at the given position. The sprite will be drawn starting at the X and Y position, with the top-left corner of the sprite at the X and Y position. The sprite will be drawn on top of any existing content at that position, according to its Z-index. If it is already drawn, it will be redrawn at the new position.

If data is NULL, the sprite will not be drawn.

Parameters
xThe X position of the sprite.
yThe Y position of the sprite.
spriteThe sprite to draw.
Returns
1 if the sprite was drawn, 0 if not or an error occurred.

◆ Sprite_fillAnsi()

int Sprite_fillAnsi ( CmdFX_Sprite * sprite,
int x,
int y,
char * ansi,
int width,
int height )

Fills positions in the sprite with an ANSI code.

This method sets the ANSI code at a specific rectangle in the sprite. The fill will start at the given position and fill the specified width and height. If a position is out of bounds, it will be skipped.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
ansiThe ANSI code to set.
widthThe width of the fill.
heightThe height of the fill.
Returns
1 if the ANSI code was set, 0 if an error occurred.

◆ Sprite_fillChar()

int Sprite_fillChar ( CmdFX_Sprite * sprite,
int x,
int y,
char c,
int width,
int height )

Fills positions in the sprite.

This method sets the character at a specific rectangle in the sprite. The fill will start at the given position and fill the specified width and height. If a position is out of bounds, it will be skipped.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
cThe character to set.
widthThe width of the fill.
heightThe height of the fill.
Returns
1 if the character was set, 0 if an error occurred.

◆ Sprite_fillCharAll()

int Sprite_fillCharAll ( CmdFX_Sprite * sprite,
char c )

Sets the character at all positions in the sprite.

This method sets the character at all positions in the sprite. The character will be set for every position in the sprite, starting from the top-left corner. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
cThe character to set.
Returns
1 if the character was set, 0 if an error occurred.

◆ Sprite_fillCharAllEmpty()

int Sprite_fillCharAllEmpty ( CmdFX_Sprite * sprite,
char c )

Sets the character at all positions in the sprite where there isn't a character.

This method sets the character at all positions in the sprite. The character will be set for every position in the sprite, starting from the top-left corner. If an error occurs, the method will return 0.

This method will skip any positions that are already filled with a character. Existing ANSI codes at empty positions will be preserved.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
cThe character to set.
Returns
1 if the character was set, 0 if an error occurred.

◆ Sprite_fillCharEmpty()

int Sprite_fillCharEmpty ( CmdFX_Sprite * sprite,
int x,
int y,
char c,
int width,
int height )

Fills positions in the sprite where there isn't a character.

This method sets the character at a specific rectangle in the sprite. The fill will start at the given position and fill the specified width and height. If a position is out of bounds, it will be skipped.

This method will skip any positions that are already filled with a character. Existing ANSI codes at empty positions will be preserved.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
cThe character to set.
widthThe width of the fill.
heightThe height of the fill.
Returns
1 if the character was set, 0 if an error occurred.

◆ Sprite_free()

void Sprite_free ( CmdFX_Sprite * sprite)

Frees the memory allocated for a sprite.

If the sprite is currently drawn, it will be removed.

Parameters
spriteThe sprite to free.

◆ Sprite_getCollidingSprites()

CmdFX_Sprite ** Sprite_getCollidingSprites ( CmdFX_Sprite * sprite)

Gets the sprites that are colliding with the given sprite.

This method returns an array of pointers to the sprites that are colliding with the given sprite. The array is terminated with a NULL pointer.

The array must be freed by the caller when it is no longer needed.

Parameters
spriteThe sprite to check for collisions.
Returns
An array of pointers to the colliding sprites.

◆ Sprite_getRotationAngle()

double Sprite_getRotationAngle ( CmdFX_Sprite * sprite)

Gets the rotation angle of the sprite.

This method returns the rotation angle of the sprite in radians. The angle will be between -PI and PI. If the sprite is not rotated, the method will return 0. Rotation is calculated by the number of whitespace characters in the sprite, meaning this method relies on whether it is visually rotated or not.

Parameters
spriteThe sprite to get the rotation angle of.
Returns
The rotation angle of the sprite in radians.

◆ Sprite_hFlip()

int Sprite_hFlip ( CmdFX_Sprite * sprite)

Flips the sprite horizontally.

This method flips the sprite horizontally. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to flip.
Returns
0 if the sprite was flipped, -1 if an error occurred.

◆ Sprite_isColliding()

int Sprite_isColliding ( CmdFX_Sprite * sprite1,
CmdFX_Sprite * sprite2 )

Checks if two sprites are colliding.

Parameters
sprite1The first sprite.
sprite2The second sprite.
Returns
1 if the sprites are colliding, 0 otherwise.

◆ Sprite_isOnBottom()

int Sprite_isOnBottom ( CmdFX_Sprite * sprite,
int x,
int y )

Gets whether the sprite is the bottom-most sprite at the given position.

This method checks if the sprite is the bottom-most sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0. "Bottom-most" refers to the sprite with the lowest Z-index.

Parameters
spriteThe sprite to check.
xThe X position.
yThe Y position.
Returns
1 if the sprite is on the bottom, 0 otherwise.

◆ Sprite_isOnTop()

int Sprite_isOnTop ( CmdFX_Sprite * sprite,
int x,
int y )

Gets whether the sprite is the top-most sprite at the given position.

This method checks if the sprite is the top-most sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0. "Top-most" refers to the sprite with the highest Z-index.

Parameters
spriteThe sprite to check.
xThe X position.
yThe Y position.
Returns
1 if the sprite is on top, 0 otherwise.

◆ Sprite_loadFromFile()

CmdFX_Sprite * Sprite_loadFromFile ( const char * path,
int z )

Creates a new sprite from a file.

This method creates a new sprite from the given file. The sprite will be loaded from the file and the Z-index will be set to the given value. The data from the file will be used, keeping ansi empty. The file must be a readable text file. The sprite should be freed with Sprite_free when it is no longer needed.

This method does not draw the sprite to the terminal. To draw the sprite, use the Sprite_draw method.

Parameters
pathThe path to the file to load the sprite from.
zThe Z-index of the sprite.
Returns
A pointer to the new sprite, or 0 if an error occurred.

◆ Sprite_moveBy()

void Sprite_moveBy ( CmdFX_Sprite * sprite,
int dx,
int dy )

Moves a sprite by the given amount.

Parameters
spriteThe sprite to move.
dxThe delta X position to move the sprite by.
dyThe delta Y position to move the sprite by.

◆ Sprite_moveTo()

void Sprite_moveTo ( CmdFX_Sprite * sprite,
int x,
int y )

Moves a sprite to the given position.

Parameters
spriteThe sprite to move.
xThe new X position of the sprite.
yThe new Y position of the sprite.

◆ Sprite_remove()

void Sprite_remove ( CmdFX_Sprite * sprite)

Removes a sprite from the terminal, making it no longer visble.

Parameters
spriteThe sprite to remove.

◆ Sprite_resize()

int Sprite_resize ( CmdFX_Sprite * sprite,
int width,
int height )

Resizes the sprite to the given dimensions.

This method is functionally identical to Sprite_resizeWithPadding, but it will pad the sprite with spaces if it is resized larger.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to resize.
widthThe new width of the sprite.
heightThe new height of the sprite.
Returns
1 if the sprite was resized, 0 if an error occurred.

◆ Sprite_resizeAndCenter()

int Sprite_resizeAndCenter ( CmdFX_Sprite * sprite,
int width,
int height )

Resizes and centers the sprite on the terminal.

This method resizes the sprite to the given width and height, and then centers the sprite on the terminal, both horizontally and vertically. It will reposition the data and ansi characters depending on whether there is whitespace surrounding other characters.

The sprite will be drawn at its new position.

Parameters
spriteThe sprite to resize and center.
widthThe new width of the sprite.
heightThe new height of the sprite.
Returns
1 if the sprite was resized and centered, 0 if an error occurred.

◆ Sprite_resizeWithPadding()

int Sprite_resizeWithPadding ( CmdFX_Sprite * sprite,
int width,
int height,
char padding )

Resizes the sprite to the given dimensions.

This method resizes the sprite to the given width and height. If the new dimensions are smaller than the current dimensions, the sprite will be cropped from the top left. If the new dimensions are larger than the current dimensions, the sprite will be padded with the provided character. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to resize.
widthThe new width of the sprite.
heightThe new height of the sprite.
paddingThe character to pad the sprite with if it is resized larger.
Returns
1 if the sprite was resized, 0 if an error occurred.

◆ Sprite_rotate()

int Sprite_rotate ( CmdFX_Sprite * sprite,
double radians )

Rotates the sprite by the given angle.

This method rotates the sprite by the given angle in radians. The sprite will be rotated around its center. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to rotate.
radiansThe angle to rotate the sprite by in radians.
Returns
0 if the sprite was rotated, -1 if an error occurred.

◆ Sprite_scale()

int Sprite_scale ( CmdFX_Sprite * sprite,
double scale )

Scales the sprite by the given factor.

This method scales the sprite by the given factor. The sprite will be scaled around its center. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to scale.
scaleThe factor to scale the sprite by.
Returns
0 if the sprite was scaled, -1 if an error occurred.

◆ Sprite_setAnsi()

int Sprite_setAnsi ( CmdFX_Sprite * sprite,
int x,
int y,
char * ansi )

Sets the ANSI code at the given position in the sprite.

This method sets the ANSI code at the given position in the sprite. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
ansiThe ANSI code to set.
Returns
1 if the ANSI code was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setAnsiAll()

int Sprite_setAnsiAll ( CmdFX_Sprite * sprite,
char * ansi )

Sets the character at all positions in the sprite.

This method sets the character at all positions in the sprite. The character will be set for every position in the sprite, starting from the top-left corner. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
ansiThe ANSI code to set.
Returns
1 if the character was set, 0 if an error occurred.

◆ Sprite_setBackground()

int Sprite_setBackground ( CmdFX_Sprite * sprite,
int x,
int y,
int rgb )

Sets the background color of the sprite at the given position.

This method sets the background color of the sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
rgbThe RGB color to set.
Returns
1 if the color was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setBackgroundAll()

int Sprite_setBackgroundAll ( CmdFX_Sprite * sprite,
int rgb )

Sets the background color of the sprite at the given position.

This method sets the background color of the sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
rgbThe RGB color to set.
Returns
1 if the color was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setBackgroundAll256()

int Sprite_setBackgroundAll256 ( CmdFX_Sprite * sprite,
int color )

Sets the background color of the sprite at the given position using 256-bit color codes.

This method sets the background color of the sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
colorThe 256-color code to set.
Returns
1 if the color was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setBackgroundGradient()

int Sprite_setBackgroundGradient ( CmdFX_Sprite * sprite,
int x,
int y,
int width,
int height,
enum CmdFX_GradientDirection direction,
int numColors,
... )

Sets a background gradient using RGB colors for a specified section of the sprite.

This method sets a background gradient using RGB colors between multiple colors. The gradient will be applied to the sprite starting at the given position and extending for the given width and height. The direction of the gradient will be determined by the direction parameter. The colors should be specified as RGB values in the format 0xRRGGBB. Non-integer values will not be accepted.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
widthThe width of the gradient.
heightThe height of the gradient.
directionThe direction of the gradient.
numColorsThe number of colors in the gradient.
...A variable list of RGB colors in the gradient as an integer.
Returns
1 if the gradient was set, 0 if an error occurred.

◆ Sprite_setBackgroundGradientAll()

int Sprite_setBackgroundGradientAll ( CmdFX_Sprite * sprite,
enum CmdFX_GradientDirection direction,
int numColors,
... )

Sets a background gradient using RGB colors.

This method sets a background gradient using RGB colors between multiple colors. The gradient will be applied to the entire sprite. The direction of the gradient will be determined by the direction parameter. The colors should be specified as RGB values in the format 0xRRGGBB. Non-integer values will not be accepted.

Parameters
spriteThe sprite to modify.
directionThe direction of the gradient.
numColorsThe number of colors in the gradient.
...A variable list of RGB colors in the gradient as an integer.
Returns
1 if the gradient was set, 0 if an error occurred.

◆ Sprite_setChar()

int Sprite_setChar ( CmdFX_Sprite * sprite,
int x,
int y,
char c )

Sets the character at the given position in the sprite.

This method sets the character at the given position in the sprite. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the character if the sprite is currently drawn.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
cThe character to set.
Returns
1 if the character was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setData()

int Sprite_setData ( CmdFX_Sprite * sprite,
char ** data )

Sets the text data for the sprite.

This method sets the text data for the sprite. The text data should be a 2D array of characters. This will resize the width and height of the sprite to match the dimensions of the text data. If an error occurs, the method will return 0.

If the size is different than ansi, the ansi will be resized to match the new size. If the new size is larger, the new positions will be filled with NULL. If the new size is smaller, then ansi will be cropped from the top-left.

Parameters
spriteThe sprite to modify.
dataThe text data to set.
Returns
1 if the data was set, 0 if an error occurred.

◆ Sprite_setForeground()

int Sprite_setForeground ( CmdFX_Sprite * sprite,
int x,
int y,
int rgb )

Sets the foreground color of the sprite at the given position.

This method sets the foreground color of the sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
rgbThe RGB color to set.
Returns
1 if the color was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setForegroundAll()

int Sprite_setForegroundAll ( CmdFX_Sprite * sprite,
int rgb )

Sets the foreground color of the sprite at the given position.

This method sets the foreground color of the sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
rgbThe RGB color to set.
Returns
1 if the color was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setForegroundAll256()

int Sprite_setForegroundAll256 ( CmdFX_Sprite * sprite,
int color )

Sets the foreground color of the sprite at the given position using 256-bit color codes.

This method sets the foreground color of the sprite at the given position. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the sprite. If the position is out of bounds, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to modify.
colorThe 256-color code to set.
Returns
1 if the color was set, 0 if the position is out of bounds or an error occurred.

◆ Sprite_setForegroundGradient()

int Sprite_setForegroundGradient ( CmdFX_Sprite * sprite,
int x,
int y,
int width,
int height,
enum CmdFX_GradientDirection direction,
int numColors,
... )

Sets a foreground gradient using RGB colors for a specified section of the sprite.

This method sets a foreground gradient using RGB colors between multiple colors. The gradient will be applied to the sprite starting at the given position and extending for the given width and height. The direction of the gradient will be determined by the direction parameter. The colors should be specified as RGB values in the format 0xRRGGBB. Non-integer values will not be accepted.

Parameters
spriteThe sprite to modify.
xThe X position in the sprite.
yThe Y position in the sprite.
widthThe width of the gradient.
heightThe height of the gradient.
directionThe direction of the gradient.
numColorsThe number of colors in the gradient.
...A variable list of RGB colors in the gradient as an integer.
Returns
1 if the gradient was set, 0 if an error occurred.

◆ Sprite_setForegroundGradientAll()

int Sprite_setForegroundGradientAll ( CmdFX_Sprite * sprite,
enum CmdFX_GradientDirection direction,
int numColors,
... )

Sets a foreground gradient using RGB colors.

This method sets a foreground gradient using RGB colors between multiple colors. The gradient will be applied to the entire sprite. The direction of the gradient will be determined by the direction parameter. The colors should be specified as RGB values in the format 0xRRGGBB. Non-integer values will not be accepted.

Parameters
spriteThe sprite to modify.
directionThe direction of the gradient.
numColorsThe number of colors in the gradient.
...A variable list of RGB colors in the gradient as an integer.
Returns
1 if the gradient was set, 0 if an error occurred.

◆ Sprite_transpose()

int Sprite_transpose ( CmdFX_Sprite * sprite)

Transposes the sprite.

This method transposes the sprite, swapping the rows and columns. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to transpose.
Returns
0 if the sprite was transposed, -1 if an error occurred.

◆ Sprite_vFlip()

int Sprite_vFlip ( CmdFX_Sprite * sprite)

Flips the sprite vertically.

This method flips the sprite vertically. If an error occurs, the method will return 0.

This method will also redraw the sprite if it is currently drawn.

Parameters
spriteThe sprite to flip.
Returns
0 if the sprite was flipped, -1 if an error occurred.