|
Sista v3.0.0-beta.10
C++ lightweight OS-agnostic library for terminal animations and videogames
|
Implementation of the C API for Sista. More...

Functions | |
| static void | sista_set_last_error (int code, const char *message) |
| static void | sista_clear_last_error () |
| FieldHandler_t | sista_createField (size_t width, size_t height) |
| Creates a Field with the specified width and height. | |
| int | sista_destroyField (FieldHandler_t field) |
| Deallocates the Field from memory. | |
| SwappableFieldHandler_t | sista_createSwappableField (size_t width, size_t height) |
| Creates a SwappableField with the specified width and height. | |
| int | sista_destroySwappableField (SwappableFieldHandler_t field) |
| Deallocates the SwappableField from memory. | |
| int | sista_printField (FieldHandler_t field, char border) |
| Prints the specified Field with a given border. | |
| int | sista_printSwappableField (SwappableFieldHandler_t field, char border) |
| Prints the specified Field with a given border. | |
| int | sista_resetAnsi () |
| Resets ANSI settings to default. | |
| int | sista_setForegroundColor (enum sista_ForegroundColor color) |
| Sets the foreground color using a predefined color. | |
| int | sista_setBackgroundColor (enum sista_BackgroundColor color) |
| Sets the background color using a predefined color. | |
| int | sista_setAttribute (enum sista_Attribute attribute) |
| Sets a text attribute. | |
| int | sista_resetAttribute (enum sista_Attribute attribute) |
| Resets a text attribute. | |
| int | sista_setForegroundColorRGB (const struct sista_RGBColor *color) |
| Sets the foreground color using an RGB color. | |
| int | sista_setBackgroundColorRGB (const struct sista_RGBColor *color) |
| Sets the background color using an RGB color. | |
| ANSISettingsHandler_t | sista_createANSISettings (enum sista_ForegroundColor fgColor, enum sista_BackgroundColor bgColor, enum sista_Attribute attribute) |
| Creates an ANSISettings object. | |
| ANSISettingsHandler_t | sista_createANSISettingsRGB (struct sista_RGBColor fgColor, struct sista_RGBColor bgColor, sista_Attribute attribute) |
| int | sista_destroyANSISettings (ANSISettingsHandler_t settings) |
| Deallocates the ANSISettings from memory. | |
| int | sista_applyANSISettings (ANSISettingsHandler_t settings) |
| Applies the ANSI settings to the terminal. | |
| BorderHandler_t | sista_createBorder (char symbol, ANSISettingsHandler_t settings) |
| Creates a Border object. | |
| int | sista_destroyBorder (BorderHandler_t border) |
| Deallocates the Border from memory. | |
| int | sista_printFieldWithBorder (FieldHandler_t field, BorderHandler_t border) |
| Prints the field with the specified border. | |
| int | sista_printSwappableFieldWithBorder (SwappableFieldHandler_t field, BorderHandler_t border) |
| Prints the field with the specified border. | |
| PawnHandler_t | sista_createPawnInSwappableField (SwappableFieldHandler_t field, char symbol, ANSISettingsHandler_t settings, struct sista_Coordinates position) |
| Creates a Pawn object in a given field. | |
| PawnHandler_t | sista_createPawnInField (FieldHandler_t field, char symbol, ANSISettingsHandler_t settings, struct sista_Coordinates position) |
| Creates a Pawn object in a given field. | |
| int | sista_movePawn (FieldHandler_t field, PawnHandler_t pawn, struct sista_Coordinates destination) |
| Moves the pawn to a new position. | |
| int | sista_addPawnToSwap (SwappableFieldHandler_t field, PawnHandler_t pawn, struct sista_Coordinates destination) |
| Adds the Pawn to a list of pawns to be moved ("swapped") later. | |
| int | sista_applySwaps (SwappableFieldHandler_t field) |
| Executes all pending pawn swaps. | |
| int | sista_clearScreen (int spaces) |
| Clears the terminal screen and repositions the cursor. | |
| CursorHandler_t | sista_createCursor () |
| Creates a cursor handler. | |
| int | sista_destroyCursor (CursorHandler_t cursor) |
| Deallocates the Cursor from memory. | |
| int | sista_moveCursor (CursorHandler_t cursor, enum sista_MoveCursor direction, unsigned short amount) |
| Moves the cursor in the specified direction by a given amount. | |
| int | sista_cursorGoTo (CursorHandler_t cursor, unsigned short y, unsigned short x) |
| Moves the cursor to the specified coordinates. | |
| int | sista_cursorGoToCoordinates (CursorHandler_t cursor, struct sista_Coordinates coords) |
| Moves the cursor to the specified coordinates. | |
| const char * | sista_getVersion () |
| int | sista_getVersionMajor () |
| int | sista_getVersionMinor () |
| int | sista_getVersionPatch () |
| int | sista_getLastErrorCode () |
| Returns the last API error code for the current thread. | |
| const char * | sista_getLastErrorMessage () |
| Returns the last API error message for the current thread. | |
Variables | |
| static thread_local int | sista_last_error_code = SISTA_OK |
| static thread_local const char * | sista_last_error_message = "ok" |
Implementation of the C API for Sista.
This file contains the implementation of the C API functions declared in api.h. It provides a C-compatible interface to interact with the Sista library, allowing for operations on SwappableField objects.
| int sista_addPawnToSwap | ( | SwappableFieldHandler_t | field, |
| PawnHandler_t | pawn, | ||
| struct sista_Coordinates | destination | ||
| ) |
Adds the Pawn to a list of pawns to be moved ("swapped") later.
| field | The SwappableField containing the Pawn. |
| pawn | The Pawn to add to the swap list. |
| destination | The destination coordinates. |
enum sista_ErrorCode.This function adds the specified Pawn to a list of pawns that will be moved (swapped) when sista_executeSwaps is called. The pawn will be moved to the specified destination coordinates.
On failure, this function also updates the per-thread last-error state accessible with sista_getLastErrorCode() and sista_getLastErrorMessage().
| SISTA_OK | If the pawn was successfully added to the swap list. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| SISTA_ERR_NULL_PAWN | If pawn is NULL. |
| SISTA_ERR_OUT_OF_BOUNDS | If the destination is out of bounds. |
| SISTA_ERR_OCCUPIED | If the destination is occupied or invalid. |
| SISTA_ERR_UNKNOWN | If adding the pawn to the swap list failed for another reason. |
| int sista_applyANSISettings | ( | ANSISettingsHandler_t | settings | ) |
Applies the ANSI settings to the terminal.
| settings | The ANSISettings to apply. |
enum sista_ErrorCode.This function applies the specified ANSI settings to the terminal by outputting the corresponding ANSI escape codes to standard output.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_SETTINGS | If settings is NULL. |
| int sista_applySwaps | ( | SwappableFieldHandler_t | field | ) |
Executes all pending pawn swaps.
| field | The SwappableField containing the pawns to swap. |
enum sista_ErrorCode.This function executes all pending pawn swaps that have been added using sista_addPawnToSwap. It attempts to move each pawn to its specified destination, handling any conflicts or errors that arise.
On failure, this function also updates the per-thread last-error state accessible with sista_getLastErrorCode() and sista_getLastErrorMessage().
| SISTA_OK | If all possible (read note) swaps were successful. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| SISTA_ERR_UNKNOWN | If executing swaps failed for another reason. |
|
static |
| int sista_clearScreen | ( | int | spaces | ) |
Clears the terminal screen and repositions the cursor.
| spaces | Non-zero to clear visible content and scrollback buffer; zero to only move the cursor to the top-left corner. |
enum sista_ErrorCode.This is the C API counterpart of sista::clearScreen(bool).
| SISTA_OK | On success. |
| ANSISettingsHandler_t sista_createANSISettings | ( | enum | sista_ForegroundColor, |
| enum | sista_BackgroundColor, | ||
| enum | sista_Attribute | ||
| ) |
Creates an ANSISettings object.
| fgColor | The foreground color (predefined). |
| bgColor | The background color (predefined). |
| attribute | The text attribute to apply. |
This function allocates and initializes a new ANSISettings object. It returns a pointer that can be used to reference the ANSISettings in subsequent API calls.
| NULL | If memory allocation fails. |
| ANSISettingsHandler_t sista_createANSISettingsRGB | ( | struct sista_RGBColor | fgColor, |
| struct sista_RGBColor | bgColor, | ||
| sista_Attribute | attribute | ||
| ) |
| BorderHandler_t sista_createBorder | ( | char | symbol, |
| ANSISettingsHandler_t | settings | ||
| ) |
Creates a Border object.
| symbol | The character symbol for the border brick. |
| settings | The ANSISettings to apply to the border brick. |
This function allocates and initializes a new Border object with the specified symbol and ANSI settings. It returns a pointer that can be used to reference the Border in subsequent API calls.
| NULL | If memory allocation fails. |
| CursorHandler_t sista_createCursor | ( | ) |
Creates a cursor handler.
This function allocates and initializes a new Cursor object. It returns a pointer that can be used to reference the Cursor in subsequent API calls.
| NULL | If memory allocation fails. |
| FieldHandler_t sista_createField | ( | size_t | width, |
| size_t | height | ||
| ) |
Creates a Field with the specified width and height.
| width | The width of the Field. |
| height | The height of the Field. |
This function allocates and initializes a new Field object with the given dimensions. It returns a pointer that can be used to reference the Field in subsequent API calls.
| NULL | If memory allocation fails. |
| PawnHandler_t sista_createPawnInField | ( | FieldHandler_t | field, |
| char | symbol, | ||
| ANSISettingsHandler_t | settings, | ||
| struct sista_Coordinates | position | ||
| ) |
Creates a Pawn object in a given field.
| field | The Field to add the pawn to. |
| symbol | The character symbol for the pawn. |
| settings | The ANSISettings to apply to the pawn. |
| position | The initial position of the pawn. |
This function allocates and initializes a new Pawn object with the specified symbol, ANSI settings, and initial position. It returns a pointer that can be used to reference the Pawn in subsequent API calls.
| NULL | If creation fails for any reason. |
sista_getLastErrorCode() and sista_getLastErrorMessage() for details.| PawnHandler_t sista_createPawnInSwappableField | ( | SwappableFieldHandler_t | field, |
| char | symbol, | ||
| ANSISettingsHandler_t | settings, | ||
| struct sista_Coordinates | position | ||
| ) |
Creates a Pawn object in a given field.
| field | The SwappableField to add the pawn to. |
| symbol | The character symbol for the pawn. |
| settings | The ANSISettings to apply to the pawn. |
| position | The initial position of the pawn. |
This function allocates and initializes a new Pawn object with the specified symbol, ANSI settings, and initial position. It returns a pointer that can be used to reference the Pawn in subsequent API calls.
| NULL | If creation fails for any reason. |
sista_getLastErrorCode() and sista_getLastErrorMessage() for details.| SwappableFieldHandler_t sista_createSwappableField | ( | size_t | width, |
| size_t | height | ||
| ) |
Creates a SwappableField with the specified width and height.
| width | The width of the SwappableField. |
| height | The height of the SwappableField. |
This function allocates and initializes a new SwappableField object with the given dimensions. It returns a pointer that can be used to reference the SwappableField in subsequent API calls.
| NULL | If memory allocation fails. |
| int sista_cursorGoTo | ( | CursorHandler_t | cursor, |
| unsigned short | y, | ||
| unsigned short | x | ||
| ) |
Moves the cursor to the specified coordinates.
| cursor | The Cursor handler. |
| y | The y coordinate (row). |
| x | The x coordinate (column). |
enum sista_ErrorCode.This function moves the terminal cursor to the specified (y, x) coordinates using ANSI escape codes.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_CURSOR | If cursor is NULL. |
| int sista_cursorGoToCoordinates | ( | CursorHandler_t | cursor, |
| struct sista_Coordinates | coords | ||
| ) |
Moves the cursor to the specified coordinates.
| cursor | The Cursor handler. |
| coords | The coordinates struct containing y and x. |
enum sista_ErrorCode.This function moves the terminal cursor to the specified (y, x) coordinates using ANSI escape codes.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_CURSOR | If cursor is NULL. |
| int sista_destroyANSISettings | ( | ANSISettingsHandler_t | settings | ) |
Deallocates the ANSISettings from memory.
| settings | The ANSISettings to delete. |
enum sista_ErrorCode.This function deallocates the ANSISettings from memory through the opaque handler pointing to it.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_SETTINGS | If settings is NULL. |
| int sista_destroyBorder | ( | BorderHandler_t | border | ) |
Deallocates the Border from memory.
| border | The Border to delete. |
enum sista_ErrorCode.This function deallocates the Border from memory through the opaque handler pointing to it.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_BORDER | If border is NULL. |
| int sista_destroyCursor | ( | CursorHandler_t | cursor | ) |
Deallocates the Cursor from memory.
| cursor | The Cursor to delete. |
enum sista_ErrorCode.This function deallocates the Cursor from memory through the opaque handler pointing to it.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_CURSOR | If cursor is NULL. |
| int sista_destroyField | ( | FieldHandler_t | field | ) |
Deallocates the Field from memory.
| field | The Field to delete |
enum sista_ErrorCode.This function deallocates the Field from memory through the opaque handler pointing to it.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| int sista_destroySwappableField | ( | SwappableFieldHandler_t | field | ) |
Deallocates the SwappableField from memory.
| field | The SwappableField to delete |
enum sista_ErrorCode.This function deallocates the SwappableField from memory through the opaque handler pointing to it.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| int sista_getLastErrorCode | ( | ) |
Returns the last API error code for the current thread.
This value is updated by API functions that expose failure diagnostics, including functions that return NULL and functions that return a status code from enum sista_ErrorCode.
Successful calls participating in this model reset the value to SISTA_OK.
enum sista_ErrorCode. | const char * sista_getLastErrorMessage | ( | ) |
Returns the last API error message for the current thread.
The returned pointer remains valid until the next API call on the same thread that updates the last-error state.
Successful calls participating in this model reset the message to "ok". Call this function immediately after a failing API call to read diagnostics.
| const char * sista_getVersion | ( | ) |
| int sista_getVersionMajor | ( | ) |
| int sista_getVersionMinor | ( | ) |
| int sista_getVersionPatch | ( | ) |
| int sista_moveCursor | ( | CursorHandler_t | cursor, |
| enum | sista_MoveCursor, | ||
| unsigned short | amount | ||
| ) |
Moves the cursor in the specified direction by a given amount.
| cursor | The Cursor handler. |
| direction | The direction to move the cursor. |
| amount | The number of positions to move the cursor. |
enum sista_ErrorCode.This function moves the terminal cursor in the specified direction by the given amount using ANSI escape codes.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_CURSOR | If cursor is NULL. |
| int sista_movePawn | ( | FieldHandler_t | field, |
| PawnHandler_t | pawn, | ||
| struct sista_Coordinates | destination | ||
| ) |
Moves the pawn to a new position.
| field | The Field containing the Pawn. |
| pawn | The Pawn to move. |
| destination | The destination coordinates. |
enum sista_ErrorCode.On failure, this function also updates the per-thread last-error state accessible with sista_getLastErrorCode() and sista_getLastErrorMessage().
| SISTA_OK | If the move was successful. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| SISTA_ERR_NULL_PAWN | If pawn is NULL. |
| SISTA_ERR_OUT_OF_BOUNDS | If the destination is out of bounds. |
| SISTA_ERR_OCCUPIED | If the destination is occupied or invalid. |
| SISTA_ERR_UNKNOWN | If the move failed for another reason. |
| int sista_printField | ( | FieldHandler_t | field, |
| char | border | ||
| ) |
Prints the specified Field with a given border.
| field | The Field. |
| border | The border character to use. |
enum sista_ErrorCode.This function prints the entire field to the terminal, using the specified character as the border around the field.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| int sista_printFieldWithBorder | ( | FieldHandler_t | field, |
| BorderHandler_t | border | ||
| ) |
Prints the field with the specified border.
| field | The Field to print. |
| border | The Border to print. |
enum sista_ErrorCode.This function prints the entire field to the terminal, using the specified Border object to draw the border around the field.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| SISTA_ERR_NULL_BORDER | If border is NULL. |
| int sista_printSwappableField | ( | SwappableFieldHandler_t | field, |
| char | border | ||
| ) |
Prints the specified Field with a given border.
| field | The SwappableField. |
| border | The border character to use. |
enum sista_ErrorCode.This function prints the entire field to the terminal, using the specified character as the border around the field.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| int sista_printSwappableFieldWithBorder | ( | SwappableFieldHandler_t | field, |
| BorderHandler_t | border | ||
| ) |
Prints the field with the specified border.
| field | The SwappableField to print. |
| border | The Border to print. |
enum sista_ErrorCode.This function prints the entire field to the terminal, using the specified Border object to draw the border around the field.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_FIELD | If field is NULL. |
| SISTA_ERR_NULL_BORDER | If border is NULL. |
| int sista_resetAnsi | ( | ) |
Resets ANSI settings to default.
enum sista_ErrorCode.This function resets the terminal's ANSI settings, including colors and attributes, to their default values.
| SISTA_OK | On success. |
| int sista_resetAttribute | ( | enum | sista_Attribute | ) |
Resets a text attribute.
| attribute | The text attribute to reset. |
enum sista_ErrorCode.This function resets a text attribute, such as bold or underline, specified in the sista_Attribute enumeration. It outputs the corresponding ANSI escape code to standard output.
| SISTA_OK | On success. |
|
static |
| int sista_setAttribute | ( | enum | sista_Attribute | ) |
Sets a text attribute.
| attribute | The text attribute to set. |
enum sista_ErrorCode.This function sets a text attribute, such as bold or underline, specified in the sista_Attribute enumeration. It outputs the corresponding ANSI escape code to standard output.
| SISTA_OK | On success. |
| int sista_setBackgroundColor | ( | enum | sista_BackgroundColor | ) |
Sets the background color using a predefined color.
| color | The predefined background color to set. |
enum sista_ErrorCode.This function sets the terminal's background color to one of the predefined colors specified in the sista_BackgroundColor enumeration. It outputs the corresponding ANSI escape code to standard output.
| SISTA_OK | On success. |
| int sista_setBackgroundColorRGB | ( | const struct sista_RGBColor * | color | ) |
Sets the background color using an RGB color.
| color | A pointer to a sista_RGBColor struct defining the color. |
enum sista_ErrorCode.This function sets the terminal's background color using the RGB components specified in the provided sista_RGBColor struct. It outputs the corresponding ANSI escape code to standard output.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_COLOR | If color is NULL. |
| int sista_setForegroundColor | ( | enum | sista_ForegroundColor | ) |
Sets the foreground color using a predefined color.
| color | The predefined foreground color to set. |
enum sista_ErrorCode.This function sets the terminal's foreground color to one of the predefined colors specified in the sista_ForegroundColor enumeration. It outputs the corresponding ANSI escape code to standard output.
| SISTA_OK | On success. |
| int sista_setForegroundColorRGB | ( | const struct sista_RGBColor * | color | ) |
Sets the foreground color using an RGB color.
| color | A pointer to a sista_RGBColor struct defining the color. |
enum sista_ErrorCode.This function sets the terminal's foreground color using the RGB components specified in the provided sista_RGBColor struct. It outputs the corresponding ANSI escape code to standard output.
| SISTA_OK | On success. |
| SISTA_ERR_NULL_COLOR | If color is NULL. |
|
static |
|
static |