Scenes API for CmdFX. More...

Classes
struct	CmdFX_Scene
	Represents a CmdFX Scene. More...

Macros
#define	MAX_REGISTERED_SCENES 1024
	Represents the maximum number of registered scenes that can be stored.

Typedefs
typedef struct CmdFX_Scene	CmdFX_Scene
	Represents a CmdFX Scene.

Functions
CmdFX_Scene **	Scene_getDrawnScenes ()
	Gets a list of all scenes that are drawn on the screen.

int	Scene_getDrawnScenesCount ()
	Gets the number of scenes that are drawn on the screen.

CmdFX_Scene *	Scene_create (int width, int height)
	Creates an empty scene with a specified width and height.

CmdFX_Scene *	Scene_createFilled (int width, int height, char c, char *ansi, int z)
	Creates a filled scene with a specified width, height, and character.

CmdFX_Scene *	Scene_createFromData (char data, char *ansiData)
	Creates a scene from a 2D array of characters and ANSI strings.

int	Scene_clear (CmdFX_Scene *scene)
	Clears a scene of its data.

int	Scene_draw (CmdFX_Scene *scene, int x, int y)
	Draws a scene at the specified position on the screen.

int	Scene_drawPortion (CmdFX_Scene *scene, int x, int y, int sx, int sy, int width, int height)
	Draws a portion of a scene at the specified position on the screen.

CmdFX_Scene *	Scene_getSceneAt (int x, int y)
	Gets the scene at the specified position on the screen.

int	Scene_isOnTop (CmdFX_Scene *scene)
	Checks if the specified scene is on top of the screen.

int	Scene_isOnTopAt (CmdFX_Scene *scene, int x, int y)
	Checks if the specified scene is on top at the specified position on the screen.

int	Scene_isOnBottom (CmdFX_Scene *scene)
	Checks if the specified scene is on the bottom of the screen.

int	Scene_isOnBottomAt (CmdFX_Scene *scene, int x, int y)
	Checks if the specified scene is on the bottom at the specified position on the screen.

int	Scene_remove (CmdFX_Scene *scene)
	Removes a scene from the screen.

int	Scene_isEmpty (CmdFX_Scene *scene)
	Checks if the specified scene is empty.

int	Scene_switchTo (CmdFX_Scene *scene, int x, int y)
	Removes all of the currently drawn scenes, only leaving this scene.

int	Scene_free (CmdFX_Scene *scene)
	Destroys the scene, freeing the memory allocated.

CmdFX_Scene **	Scene_getRegisteredScenes ()
	Gets a list of all registered scenes.

int	Scene_getRegisteredScenesCount ()
	Gets the number of registered scenes.

int	Scene_register (CmdFX_Scene *scene)
	Registers a scene with the Scene Engine.

int	Scene_unregister (CmdFX_Scene *scene)
	Unregisters a scene with the Scene Engine.

int	Scene_drawRegistered (int uid, int x, int y)
	Draws a registered scene at the specified position on the screen.

int	Scene_switchToRegistered (int uid, int x, int y)
	Removes all of the currently drawn scenes, only leaving the registered scene with the specified unique identifier.

int	Scene_scroll (int uid, int dx, int dy)
	Scrolls the scene by the specified amount.

void	tickCmdFXSceneEngine ()
	Ticks the CmdFX Scene Engine.

int	beginCmdFXSceneEngine ()
	Begins the CmdFX Scene Engine.

int	endCmdFXSceneEngine ()
	Ends the CmdFX Scene Engine.

int	Scene_setData (CmdFX_Scene scene, char *data)
	Sets the data of the scene.

int	Scene_setChar (CmdFX_Scene *scene, int x, int y, char c)
	Sets the character at the specified position in the scene.

int	Scene_setAnsiData (CmdFX_Scene scene, char **ansiData)
	Sets the ANSI data of the scene.

int	Scene_appendAnsiData (CmdFX_Scene scene, char **ansiData)
	Appends the ANSi data to the current ansi data, setting it if it is not currently set.

int	Scene_setForeground (CmdFX_Scene *scene, int x, int y, int width, int height, int rgb)
	Fills the foreground of the scene with the specified RGB color.

int	Scene_setForegroundAll (CmdFX_Scene *scene, int rgb)
	Fills the entirety of the foreground of the scene with the specified RGB color.

int	Scene_setBackground (CmdFX_Scene *scene, int x, int y, int width, int height, int rgb)
	Fills the background of the scene with the specified RGB color.

int	Scene_setBackgroundAll (CmdFX_Scene *scene, int rgb)
	Fills the entirety of the background of the scene with the specified RGB color.

Detailed Description

Scenes API for CmdFX.

Author: Gregory Mitchell (me@gm.nosp@m.itch.nosp@m.215.x.nosp@m.yz)

Version: 0.1.3

Date: 2025-03-20

Copyright: Copyright (c) 2025

Macro Definition Documentation

◆ MAX_REGISTERED_SCENES

#define MAX_REGISTERED_SCENES 1024

Represents the maximum number of registered scenes that can be stored.

The maximum number of registered scenes that can be stored is 256. This is the maximum number of scenes that can be registered with the Scene Engine at any given time.

Typedef Documentation

◆ CmdFX_Scene

typedef struct CmdFX_Scene CmdFX_Scene

Represents a CmdFX Scene.

A CmdFX Scene is a storage buffer for different characters on the screen. It is drawn using the cnvas API and should be used when displaying large amounts of characters at a time.

Function Documentation

◆ beginCmdFXSceneEngine()

int beginCmdFXSceneEngine ( )

Begins the CmdFX Scene Engine.

This function initializes the CmdFX Scene Engine. The Scene Engine is responsible for managing all scenes that are drawn on the screen. It will automatically redraw scenes each frame if necessary for registered scenes.

Returns: 0 if the Scene Engine was started successfully, or -1 if an error occurred.

◆ endCmdFXSceneEngine()

int endCmdFXSceneEngine ( )

Ends the CmdFX Scene Engine.

This function stops the CmdFX Scene Engine. The Scene Engine will no longer manage scenes that are drawn on the screen. Scenes will no longer be automatically redrawn each frame.

Returns: 0 if the Scene Engine was stopped successfully, or -1 if an error occurred.

◆ Scene_appendAnsiData()

int Scene_appendAnsiData	(	CmdFX_Scene *	scene,
		char ***	ansiData )

Appends the ANSi data to the current ansi data, setting it if it is not currently set.

This function appends the ANSI data to the current ANSI data of the scene. The width and height of the scene must match the width and height of the 2D array. The ANSI data field will be resized to match the new size. If an error occurs, the function will return -1.

The scene will be redrawn if it is currently drawn.

Parameters

scene	The scene to modify.
ansiData	The 2D array of ANSI strings to append.

Returns: 0 if the scene data was set, or -1 if an error occurred.

◆ Scene_clear()

int Scene_clear ( CmdFX_Scene * scene )

Clears a scene of its data.

This function clears the specified scene of its data. This means that all characters in the data field will be set to 0, making Scene_isEmpty return 1.

Parameters

scene The scene to clear.

Returns: 0 if the scene was cleared successfully, or -1 if an error occurred.

◆ Scene_create()

CmdFX_Scene * Scene_create	(	int	width,
		int	height )

Creates an empty scene with a specified width and height.

This function creates a new scene with the specified width and height. The scene will be empty, meaning that all characters in the data field will be set to ‘’ '`.

The width and height parameters must be greater than 0. If either parameter is less than or equal to 0, the function will return NULL.

Parameters

width	The width of the scene.
height	The height of the scene.

Returns: A pointer to the newly created scene, or NULL if the scene could not be created.

◆ Scene_createFilled()

CmdFX_Scene * Scene_createFilled	(	int	width,
		int	height,
		char	c,
		char *	ansi,
		int	z )

Creates a filled scene with a specified width, height, and character.

This function creates a new scene with the specified width and height. The scene will be filled with the specified character. The ANSI data will be set to the specified ANSI string.

The width and height parameters must be greater than 0. If either parameter is less than or equal to 0, the function will return NULL.

Parameters

width	The width of the scene.
height	The height of the scene.
c	The character to fill the scene with.
ansi	The ANSI string to fill the scene with.
z	The Z index of the scene.

Returns: A pointer to the newly created scene, or NULL if the scene could not be created.

◆ Scene_createFromData()

CmdFX_Scene * Scene_createFromData	(	char **	data,
		char ***	ansiData )

Creates a scene from a 2D array of characters and ANSI strings.

This function creates a new scene from the specified 2D array of characters and ANSI strings. The width and height of the scene will be set to the width and height of the 2D array. Therefore, the arrays must be properly null-teminated with a NULL character at the end of each array.

The bounds will be based on the data array. If the bounds do not match, the function will return NULL.

The data parameter must not be NULL. If data is NULL, the function will return NULL. ansiData can optionally be NULL to represent no color.

Parameters

data	The 2D array of characters that represent the scene.
ansiData	The 2D array of ANSI strings that represent the scene.

Returns: A pointer to the newly created scene, or NULL if the scene could not be created.

◆ Scene_draw()

int Scene_draw	(	CmdFX_Scene *	scene,
		int	x,
		int	y )

Draws a scene at the specified position on the screen.

This function draws the specified scene at the specified position on the screen. The scene will be drawn using the Canvas API, which means that it will disappear if a Sprite is drawn over it. The Scene Engine will automatically redraw the scene each frame if necessary.

Parameters

scene	The scene to draw.
x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.

Returns: 0 if the scene was drawn successfully, or -1 if an error occurred.

◆ Scene_drawPortion()

int Scene_drawPortion	(	CmdFX_Scene *	scene,
		int	x,
		int	y,
		int	sx,
		int	sy,
		int	width,
		int	height )

Draws a portion of a scene at the specified position on the screen.

This function draws a portion of the specified scene at the specified position on the screen. The portion is defined by the specified x, y, width, and height parameters. The scene will be drawn using the Canvas API, which means that it will disappear if a Sprite is drawn over it. The Scene Engine will automatically redraw the scene each frame if necessary.

The x and y parameters must be greater than or equal to 0. If either parameter is less than 0, the function will return -1.

Parameters

scene	The scene to draw.
x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.
sx	The x-coordinate of the top-left corner of the portion to draw.
sy	The y-coordinate of the top-left corner of the portion to draw.
width	The width of the portion to draw.
height	The height of the portion to draw.

Returns: 0 if the scene was drawn successfully, or -1 if an error occurred.

◆ Scene_drawRegistered()

int Scene_drawRegistered	(	int	uid,
		int	x,
		int	y )

Draws a registered scene at the specified position on the screen.

This function draws the registered scene with the specified unique identifier at the specified position on the screen. The scene will be drawn using the Canvas API, which means that it will disappear if a Sprite is drawn over it. The Scene Engine will automatically redraw the scene each frame if necessary.

Parameters

uid	The unique identifier of the scene to draw.
x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.

Returns: 0 if the scene was drawn successfully, or -1 if an error occurred.

◆ Scene_free()

int Scene_free ( CmdFX_Scene * scene )

Destroys the scene, freeing the memory allocated.

This function frees the memory allocated for the specified scene. After calling this function, the scene should no longer be used.

Parameters

scene The scene to free.

Returns: 0 if the scene was freed successfully, or -1 if an error occurred.

◆ Scene_getDrawnScenes()

CmdFX_Scene ** Scene_getDrawnScenes ( )

Gets a list of all scenes that are drawn on the screen.

Returns: An array of pointers to all scenes that are drawn on the screen.

◆ Scene_getDrawnScenesCount()

int Scene_getDrawnScenesCount ( )

Gets the number of scenes that are drawn on the screen.

Returns: The number of scenes that are drawn on the screen.

◆ Scene_getRegisteredScenes()

CmdFX_Scene ** Scene_getRegisteredScenes ( )

Gets a list of all registered scenes.

Returns: An array of pointers to all registered scenes.

◆ Scene_getRegisteredScenesCount()

int Scene_getRegisteredScenesCount ( )

Gets the number of registered scenes.

Returns: The number of registered scenes.

◆ Scene_getSceneAt()

CmdFX_Scene * Scene_getSceneAt	(	int	x,
		int	y )

Gets the scene at the specified position on the screen.

This function gets the top-most scene at the specified position on the screen. The scene will be drawn using the Canvas API, which means that it will disappear if a Sprite is drawn over it. The Scene Engine will automatically redraw the scene each frame if necessary.

The x and y parameters must be greater than or equal to 0. If either parameter is less than 0, the function will return NULL.

Parameters

x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.

Returns: A pointer to the scene at the specified position, or NULL if no scene was found.

◆ Scene_isEmpty()

int Scene_isEmpty ( CmdFX_Scene * scene )

Checks if the specified scene is empty.

This function checks if the specified scene is empty. A scene is considered empty if all characters in the data field are set to 0.

Parameters

scene The scene to check.

Returns: 1 if the scene is empty, or 0 if the scene is not empty.

◆ Scene_isOnBottom()

int Scene_isOnBottom ( CmdFX_Scene * scene )

Checks if the specified scene is on the bottom of the screen.

This function checks if the specified scene is on the bottom of the screen. A scene is considered to be on the bottom if it is the bottom-most scene at its position on the screen according to scene->z.

Parameters

scene The scene to check.

Returns: 1 if the scene is on the bottom, or 0 if the scene is not on bottom.

◆ Scene_isOnBottomAt()

int Scene_isOnBottomAt	(	CmdFX_Scene *	scene,
		int	x,
		int	y )

Checks if the specified scene is on the bottom at the specified position on the screen.

This function checks if the specified scene is on the bottom at the specified position on the screen. A scene is considered to be on the bottom if it is the bottom-most scene at its position on the screen according to scene->z.

Parameters

scene	The scene to check.
x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.

Returns: 1 if the scene is on bottom, or 0 if the scene is not on bottom.

◆ Scene_isOnTop()

int Scene_isOnTop ( CmdFX_Scene * scene )

Checks if the specified scene is on top of the screen.

This function checks if the specified scene is on top of the screen. A scene is considered to be on top if it is the top-most scene at its position on the screen according to scene->z.

Parameters

scene The scene to check.

Returns: 1 if the scene is on top, or 0 if the scene is not on top.

◆ Scene_isOnTopAt()

int Scene_isOnTopAt	(	CmdFX_Scene *	scene,
		int	x,
		int	y )

Checks if the specified scene is on top at the specified position on the screen.

This function checks if the specified scene is on top at the specified position on the screen. A scene is considered to be on top if it is the top-most scene at its position on the screen according to scene->z.

Parameters

scene	The scene to check.
x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.

Returns: 1 if the scene is on top, or 0 if the scene is not on top.

◆ Scene_register()

int Scene_register ( CmdFX_Scene * scene )

Registers a scene with the Scene Engine.

This function registers the specified scene with the Scene Engine. This allows the Scene Engine to keep track of the scene and automatically redraw it each frame if necessary.

Parameters

scene The scene to register.

Returns: scene->uid, or -1 if an error occurred.

◆ Scene_remove()

int Scene_remove ( CmdFX_Scene * scene )

Removes a scene from the screen.

This function removes the specified scene from the screen. The scene will no longer be drawn on the screen, and the Scene Engine will stop automatically redrawing it each frame.

Parameters

scene The scene to remove.

Returns: 0 if the scene was removed successfully, or -1 if an error occurred.

◆ Scene_scroll()

int Scene_scroll	(	int	uid,
		int	dx,
		int	dy )

Scrolls the scene by the specified amount.

This function scrolls the scene by the specified amount. The amount is specified by the dx and dy parameters, which represent the amount to scroll in the x and y directions, respectively.

Scrolling refers to moving (redrawing) the specified draw bounds over by the values of dx and dy. This is useful for creating scrolling effects in the scene.

Parameters

uid	The unique identifier of the scene to scroll.
dx	The amount to scroll in the x direction.
dy	The amount to scroll in the y direction.

Returns: 0 if the scene was scrolled successfully, -1 if an error occurred.

◆ Scene_setAnsiData()

int Scene_setAnsiData	(	CmdFX_Scene *	scene,
		char ***	ansiData )

Sets the ANSI data of the scene.

This function sets the ANSI data to the current ANSI data of the scene. The width and height of the scene must match the width and height of the 2D array. The ANSI data field will be resized to match the new size. If an error occurs, the function will return -1.

The scene will be redrawn if it is currently drawn.

Parameters

scene	The scene to modify.
ansiData	The 2D array of ANSI strings to set.

Returns: 0 if the scene data was set, or -1 if an error occurred.

◆ Scene_setBackground()

int Scene_setBackground	(	CmdFX_Scene *	scene,
		int	x,
		int	y,
		int	width,
		int	height,
		int	rgb )

Fills the background of the scene with the specified RGB color.

This function fills the background of the scene with the specified RGB color. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the scene. If the position is out of bounds, the function will return -1.

Parameters

scene	The scene to modify.
x	The top-left X position in the scene.
y	The top-left Y position in the scene.
width	The width of the fill.
height	The height of the fill.
rgb	The RGB color to set.

Returns: 0 if the fill was successful, or -1 if an error occurred.

◆ Scene_setBackgroundAll()

int Scene_setBackgroundAll	(	CmdFX_Scene *	scene,
		int	rgb )

Fills the entirety of the background of the scene with the specified RGB color.

This function fills the entirety of the background of the scene with the specified RGB color. If an error occurs, the function will return -1.

Parameters

scene	The scene to modify.
rgb	The RGB color to set.

Returns: 0 if the fill was successful, or -1 if an error occurred.

◆ Scene_setChar()

int Scene_setChar	(	CmdFX_Scene *	scene,
		int	x,
		int	y,
		char	c )

Sets the character at the specified position in the scene.

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

If the scene has no data, this function will return -1.

This function will also redraw the character if the scene is currently drawn.

Parameters

scene	The scene to modify.
x	The X position in the scene.
y	The Y position in the scene.
c	The character to set.

Returns: 0 if the character was set, or -1 if the position is out of bounds.

◆ Scene_setData()

int Scene_setData	(	CmdFX_Scene *	scene,
		char **	data )

Sets the data of the scene.

This function sets the data of the scene to the specified 2D array of characters. The width and height of the scene will be set to the width and height of the 2D array. The data field will be resized to match the new size. If an error occurs, the function will return -1.

The scene will be redrawn if it is currently drawn.

Parameters

scene	The scene to modify.
data	The 2D array of characters to set.

Returns: 0 if the scene data was set, or -1 if an error occurred.

◆ Scene_setForeground()

int Scene_setForeground	(	CmdFX_Scene *	scene,
		int	x,
		int	y,
		int	width,
		int	height,
		int	rgb )

Fills the foreground of the scene with the specified RGB color.

This function fills the foreground of the scene with the specified RGB color. The position is specified by the X and Y coordinates, where (0, 0) is the top-left corner of the scene. If the position is out of bounds, the function will return -1.

Parameters

scene	The scene to modify.
x	The top-left X position in the scene.
y	The top-left Y position in the scene.
width	The width of the fill.
height	The height of the fill.
rgb	The RGB color to set.

Returns: 0 if the fill was successful, or -1 if an error occurred.

◆ Scene_setForegroundAll()

int Scene_setForegroundAll	(	CmdFX_Scene *	scene,
		int	rgb )

Fills the entirety of the foreground of the scene with the specified RGB color.

This function fills the entirety of the foreground of the scene with the specified RGB color. If an error occurs, the function will return -1.

Parameters

scene	The scene to modify.
rgb	The RGB color to set.

Returns: 0 if the fill was successful, or -1 if an error occurred.

◆ Scene_switchTo()

int Scene_switchTo	(	CmdFX_Scene *	scene,
		int	x,
		int	y )

Removes all of the currently drawn scenes, only leaving this scene.

This function removes all of the currently drawn scenes from the screen, leaving only the specified scene.

Parameters

scene	The scene to leave on the screen.
x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.

Returns: 0 if the scene was switched to successfully, or -1 if an error occurred.

◆ Scene_switchToRegistered()

int Scene_switchToRegistered	(	int	uid,
		int	x,
		int	y )

Removes all of the currently drawn scenes, only leaving the registered scene with the specified unique identifier.

This function removes all of the currently drawn scenes from the screen, leaving only the registered scene with the specified unique identifier.

Parameters

uid	The unique identifier of the scene to leave on the screen.
x	The x-coordinate of the top-left corner of the scene.
y	The y-coordinate of the top-left corner of the scene.

Returns: 0 if the scene was switched to successfully, or -1 if an error occurred.

◆ Scene_unregister()

int Scene_unregister ( CmdFX_Scene * scene )

Unregisters a scene with the Scene Engine.

This function unregisters the specified scene with the Scene Engine. This allows the Scene Engine to stop keeping track of the scene and stop automatically redrawing it each frame.

Parameters

scene The scene to unregister.

Returns: the old scene->uid, or -1 if an error occurred.

◆ tickCmdFXSceneEngine()

void tickCmdFXSceneEngine ( )

Ticks the CmdFX Scene Engine.

This function calls all of the necessary things apart of the Scene Engine to keep scenes redrawn every frame.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ MAX_REGISTERED_SCENES

Typedef Documentation

◆ CmdFX_Scene

Function Documentation

◆ beginCmdFXSceneEngine()

◆ endCmdFXSceneEngine()

◆ Scene_appendAnsiData()

◆ Scene_clear()

◆ Scene_create()

◆ Scene_createFilled()

◆ Scene_createFromData()

◆ Scene_draw()

◆ Scene_drawPortion()

◆ Scene_drawRegistered()

◆ Scene_free()

◆ Scene_getDrawnScenes()

◆ Scene_getDrawnScenesCount()

◆ Scene_getRegisteredScenes()

◆ Scene_getRegisteredScenesCount()

◆ Scene_getSceneAt()

◆ Scene_isEmpty()

◆ Scene_isOnBottom()

◆ Scene_isOnBottomAt()

◆ Scene_isOnTop()

◆ Scene_isOnTopAt()

◆ Scene_register()

◆ Scene_remove()

◆ Scene_scroll()

◆ Scene_setAnsiData()

◆ Scene_setBackground()

◆ Scene_setBackgroundAll()

◆ Scene_setChar()

◆ Scene_setData()

◆ Scene_setForeground()

◆ Scene_setForegroundAll()

◆ Scene_switchTo()

◆ Scene_switchToRegistered()

◆ Scene_unregister()

◆ tickCmdFXSceneEngine()