libdragon

https://libdragon.dev/ref
Admin
libdragon is an open-source SDK for Nintendo 64 that offers a complete N64 programming experience...
Tokens:470,074
Snippets:2,837
Trust Score:6.5
Update:11 months ago
Show doc for...
Tokens:
Raw
### Start Playing WAV64 File

Source: https://libdragon.dev/ref/wav64_8h

Starts playing a WAV64 audio file. This function initiates the audio playback process for the specified WAV64 file. It requires a pointer to the wav64_t structure and the audio channel to use for playback.

```c
void wav64_play (wav64_t *wav, int ch)
```

--------------------------------

### ym64player_play

Source: https://libdragon.dev/ref/ym64_8c

Starts the playback of a YM file using the specified YM64 player instance.

```APIDOC
## ym64player_play()

### Description
Starts playback of a YM file. You can specify the first mixer channel to use for playback.

### Method
POST (or similar, depending on context)

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
ym64player_play(player, 0);
```

### Response
#### Success Response (Return Value)
None (void function)

#### Response Example
None
```

--------------------------------

### Start Timer with Context - C

Source: https://libdragon.dev/ref/timer_8c

Starts a timer not currently in the list, reinserting it with new tick and flag parameters, a callback, and an opaque context pointer. Use start_timer if context is not needed.

```c
void start_timer_context(timer_link_t * _timer_, int _ticks_, int _flags_, timer_callback2_t _callback_, void * _ctx_);
```

--------------------------------

### Audio Initialization and Configuration

Source: https://libdragon.dev/ref/audio_8h

Initializes the audio subsystem with a specified frequency and number of buffers. It also allows installing a callback function to fill the audio buffer when needed.

```c
void audio_init (const int frequency, int numbuffers);
void audio_set_buffer_callback (audio_fill_buffer_callback fill_buffer_callback);
```

--------------------------------

### Timer Creation and Management

Source: https://libdragon.dev/ref/timer_8h

Functions for creating, starting, stopping, and deleting timers.

```APIDOC
## Timer Creation and Management

### Description
Functions for creating, starting, stopping, and deleting timers.

### Functions

#### `new_timer`
* **Description**: Create a new timer and add to list.
* **Parameters**:
    * `ticks` (int) - The timer duration in ticks.
    * `flags` (int) - Timer flags (e.g., TF_ONE_SHOT, TF_CONTINUOUS).
    * `callback` (timer_callback1_t) - The callback function to execute when the timer fires.
* **Returns**: A pointer to the newly created timer (`timer_link_t *`).

#### `new_timer_context`
* **Description**: Create a new timer with context and add to list.
* **Parameters**:
    * `ticks` (int) - The timer duration in ticks.
    * `flags` (int) - Timer flags (e.g., TF_ONE_SHOT, TF_CONTINUOUS).
    * `callback` (timer_callback2_t) - The callback function to execute when the timer fires.
    * `ctx` (void *) - A context pointer to pass to the callback function.
* **Returns**: A pointer to the newly created timer (`timer_link_t *`).

#### `start_timer`
* **Description**: Start a timer (not currently in the list).
* **Parameters**:
    * `timer` (timer_link_t *) - The timer to start.
    * `ticks` (int) - The timer duration in ticks.
    * `flags` (int) - Timer flags (e.g., TF_ONE_SHOT, TF_CONTINUOUS).
    * `callback` (timer_callback1_t) - The callback function to execute when the timer fires.

#### `start_timer_context`
* **Description**: Start a timer (not currently in the list) with context.
* **Parameters**:
    * `timer` (timer_link_t *) - The timer to start.
    * `ticks` (int) - The timer duration in ticks.
    * `flags` (int) - Timer flags (e.g., TF_ONE_SHOT, TF_CONTINUOUS).
    * `callback` (timer_callback2_t) - The callback function to execute when the timer fires.
    * `ctx` (void *) - A context pointer to pass to the callback function.

#### `restart_timer`
* **Description**: Reset a timer and add to list.
* **Parameters**:
    * `timer` (timer_link_t *) - The timer to restart.

#### `stop_timer`
* **Description**: Stop a timer and remove it from the list.
* **Parameters**:
    * `timer` (timer_link_t *) - The timer to stop.

#### `delete_timer`
* **Description**: Remove a timer from the list and delete it.
* **Parameters**:
    * `timer` (timer_link_t *) - The timer to delete.
```

--------------------------------

### Timer Creation and Management

Source: https://libdragon.dev/ref/timer_8c

Functions for creating, starting, stopping, and deleting timers. These functions allow for timers with or without a context parameter, and can be started with specific ticks, flags, and callbacks.

```c
timer_link_t * new_timer (int ticks, int flags, timer_callback1_t callback);
timer_link_t * new_timer_context (int ticks, int flags, timer_callback2_t callback, void *ctx);
void start_timer (timer_link_t *timer, int ticks, int flags, timer_callback1_t callback);
void start_timer_context (timer_link_t *timer, int ticks, int flags, timer_callback2_t callback, void *ctx);
void restart_timer (timer_link_t *timer);
void stop_timer (timer_link_t *timer);
void delete_timer (timer_link_t *timer);
```

--------------------------------

### xm64player_play

Source: https://libdragon.dev/ref/xm64_8c

Starts playback of the XM64 module. The player requires one mixer channel per XM64 channel.

```APIDOC
## xm64player_play()

### Description
Start playing the XM64 module. Notice that the player needs to use one mixer channel per each XM64 channel.

### Method
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **_player_** (xm64player_t *) - in - XM64 player
- **_first_ch_** (int) - in - Index of the first mixer channel to use for playback.

### Request Example
```c
xm64player_play(player, 0);
```

### Response
#### Success Response (void)
This function does not return a value.

#### Response Example
N/A
```

--------------------------------

### Function Documentation - 'e' prefix

Source: https://libdragon.dev/ref/globals_func_e

Lists all documented functions in libdragon whose names start with the letter 'e'. Includes links to their respective header and source files.

```APIDOC
## Functions starting with 'e'

### Description
This section documents functions within the libdragon library that begin with the letter 'e'. Each entry provides the function signature and the files where it is declared and defined.

### Method
N/A (Documentation Reference)

### Endpoint
N/A (Documentation Reference)

### Parameters
N/A (Documentation Reference)

### Request Example
N/A (Documentation Reference)

### Response
#### Success Response (N/A)
- **Function Name** (string) - The name of the function.
- **File Information** (string) - The header and source file(s) where the function is located.

#### Response Example
```
eepfs_close() : eepromfs.h, eepromfs.c
eepfs_erase() : eepromfs.c, eepfs.h
...
```
```

--------------------------------

### Example: Configuring Scene Lights with RSPQ

Source: https://libdragon.dev/ref/rspq_8c

Demonstrates how to configure scene lights using the RSPQ API. It enqueues multiple CMD_SET_LIGHT commands with light index and RGB color information, followed by a single call to rspq_flush to ensure all queued commands are processed by the RSP.

```c
uint32_t gfx_overlay_id;
#define CMD_SET_LIGHT 0x7

for (int i=0; i<MAX_LIGHTS; i++) {
    rspq_write(gfx_overlay_id, CMD_SET_LIGHT, i,
               (lights[i].r << 16) | (lights[i].g << 8) | lights[i].b);
}

// After enqueuing multiple commands, it is sufficient
// to call rspq_flush once to make sure the RSP runs them (in case
// it was idling).
rspq_flush();
```

--------------------------------

### Get TMEM Contents for Debugging (C)

Source: https://libdragon.dev/ref/rdpq__debug_8h

Acquires a dump of the current TMEM contents and returns it as a surface. This is useful for debugging purposes. The function performs a full sync and the returned surface must be freed using surface_free. The example shows how to get the TMEM contents and dump them using debug_hexdump.

```c
surface_t surf = rdpq_debug_get_tmem();
debug_hexdump(surf.buffer, 4096);
surface_free(&surf);
```

--------------------------------

### Get Display Information - C

Source: https://libdragon.dev/ref/display_8h_source

Retrieves various information about the current display configuration. This includes the number of buffers, width, height, bits per pixel, and frames per second. These functions are useful for adapting rendering to the current screen setup.

```c
uint32_t display_get_num_buffers(void)

```

```c
uint32_t display_get_width(void)

```

```c
uint32_t display_get_height(void)

```

```c
float display_get_fps(void)

```

```c
uint32_t display_get_bitdepth(void)

```

--------------------------------

### Basic Text Rendering with libdragon

Source: https://libdragon.dev/ref/rdpq__text_8h

Demonstrates the fundamental steps to initialize libdragon, load a font, register it, and print "Hello, world" to the display. It requires the rdpq library and display functionalities. Outputs rendered text to the screen.

```c
#include <libdragon.h>

enum {
    FONT_ARIAL = 1
} FONTS;

int main(void) {
    dfs_init(DFS_DEFAULT_LOCATION);
    display_init(RESOLUTION_320x240, DEPTH_16_BPP, 2, GAMMA_NONE, ANTIALIAS_RESAMPLE);
    rdpq_init();

    // Load the font and register it into the text layout engine with ID 1.
    rdpq_text_register_font(FONT_ARIAL, rdpq_font_load("rom:/Arial.font64"));

    while (1) {
        surface_t *fb = display_get();
        rdpq_attach_clear();
        rdpq_text_print(NULL, FONT_ARIAL, 20, 20, "Hello, world");
        rdpq_detach_show();
    }
}
```

--------------------------------

### Install Custom RDP Command Hook (C)

Source: https://libdragon.dev/ref/rdpq__debug_8h

Installs a custom hook function that will be called every time an RDP command is processed. This allows for custom analysis of the RDP stream. Currently, only one hook can be installed. The hook function receives a context pointer, a pointer to the RDP command, and the command size.

```c
void my_hook(void *ctx, uint64_t *cmd, int cmd_size) {
    // Custom RDP command processing logic
}

rdpq_debug_install_hook(my_hook, NULL);
```

--------------------------------

### Display Initialization and Configuration

Source: https://libdragon.dev/ref/display_8c

Functions for initializing, closing, and querying the display subsystem.

```APIDOC
## Macros

### NUM_BUFFERS
```
#define NUM_BUFFERS 32
```
Maximum number of video backbuffers.

### FPS_WINDOW
```
#define FPS_WINDOW 32
```
Number of past frames used to evaluate FPS.

## Functions

### display_init
```markdown
## display_init

### Description
Initialize the display to a particular resolution and bit depth.

### Method
void

### Parameters
- **res** (resolution_t) - Required - The desired resolution.
- **bit** (bitdepth_t) - Required - The desired bit depth.
- **num_buffers** (uint32_t) - Required - The number of buffers to use.
- **gamma** (gamma_t) - Required - The gamma correction value.
- **filters** (filter_options_t) - Required - The filter options.
```

### display_close
```markdown
## display_close

### Description
Close the display.

### Method
void
```

### display_get_width
```markdown
## display_get_width

### Description
Get the currently configured width of the display in pixels.

### Method
uint32_t
```

### display_get_height
```markdown
## display_get_height

### Description
Get the currently configured height of the display in pixels.

### Method
uint32_t
```

### display_get_bitdepth
```markdown
## display_get_bitdepth

### Description
Get the currently configured bitdepth of the display (in bytes per pixels).

### Method
uint32_t
```

### display_get_num_buffers
```markdown
## display_get_num_buffers

### Description
Get the currently configured number of buffers.

### Method
uint32_t
```

### display_get_fps
```markdown
## display_get_fps

### Description
Get the current number of frames per second being rendered.

### Method
float
```
```

--------------------------------

### Start Timer - C

Source: https://libdragon.dev/ref/timer_8c

Starts a timer that is not currently in the list, reinserting it with new tick and flag parameters, and an optional callback. Use start_timer_context for timers with associated data.

```c
void start_timer(timer_link_t * _timer_, int _ticks_, int _flags_, timer_callback1_t _callback_);
```

--------------------------------

### Audio Initialization and Configuration

Source: https://libdragon.dev/ref/audio_8h_source

Functions for initializing the audio system, setting buffer callbacks, and configuring playback frequency.

```APIDOC
## void audio_init(const int frequency, int numbuffers)

### Description
Initializes the audio subsystem with the specified playback frequency and number of internal buffers.

### Method
POST

### Endpoint
/audio

### Parameters
#### Query Parameters
- **frequency** (int) - Required - The desired playback frequency in Hz.
- **numbuffers** (int) - Required - The number of internal audio buffers to allocate.

### Request Example
```json
{
  "frequency": 44100,
  "numbuffers": 4
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful initialization.

#### Response Example
```json
{
  "message": "Audio system initialized successfully."
}
```

## void audio_set_buffer_callback(audio_fill_buffer_callback fill_buffer_callback)

### Description
Installs a callback function that will be invoked to fill the audio buffer when needed.

### Method
POST

### Endpoint
/audio/callback

### Parameters
#### Request Body
- **fill_buffer_callback** (function pointer) - Required - A pointer to the callback function that accepts a short buffer and number of samples.

### Request Example
```json
{
  "fill_buffer_callback": "my_audio_fill_function"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the callback has been set.

#### Response Example
```json
{
  "message": "Audio buffer callback set."
}
```

## int audio_get_frequency()

### Description
Retrieves the actual playback frequency of the audio system.

### Method
GET

### Endpoint
/audio/frequency

### Response
#### Success Response (200)
- **frequency** (int) - The current audio playback frequency in Hz.

#### Response Example
```json
{
  "frequency": 44100
}
```

## int audio_get_buffer_length()

### Description
Gets the number of stereo samples that can fit into an allocated audio buffer.

### Method
GET

### Endpoint
/audio/buffer-length

### Response
#### Success Response (200)
- **buffer_length** (int) - The number of stereo samples per buffer.

#### Response Example
```json
{
  "buffer_length": 1024
}
```
```

--------------------------------

### EEPROM Filesystem Initialization

Source: https://libdragon.dev/ref/eepromfs_8c

Initializes the EEPROM filesystem with a given set of file entries.

```APIDOC
## eepfs_init

### Description
Initializes the EEPROM filesystem.

### Method
int

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
const eepfs_entry_t my_entries[] = { ... };
size_t count = sizeof(my_entries) / sizeof(my_entries[0]);
int result = eepfs_init(my_entries, count);
```

### Response
#### Success Response (0)
- **int** - Returns 0 on success.

#### Error Response (-1)
- **int** - Returns -1 on failure.

#### Response Example
```json
0
```
```

--------------------------------

### Install Custom RDP Command Hook

Source: https://libdragon.dev/ref/rdpq__debug_8h

Allows installation of a custom callback function (`hook`) that is invoked every time an RDP command is processed. The `ctx` parameter provides user-defined context.

```c
void rdpq_debug_install_hook(void(*hook)(void *ctx, uint64_t *cmd, int cmd_size), void *ctx);
```

--------------------------------

### AY8910 Macros for Configuration and Output

Source: https://libdragon.dev/ref/ay8910_8c

Defines for AY8910 tracing, debugging output, volume attenuation, and sample conversion. These macros help in configuring the AY8910's behavior and preparing audio samples for output.

```c
#define AY8910_TRACE 0
#define tracef(fmt, ...) ({ })
#define V(f) ((f) * AY8910_VOLUME_ATTENUATE)
#define SAMPLE_CONV(f) ((f) * 65535.0f - 32768.0f)
#define OUTS(s)
#define OUT(s_)
```

```c
#define OUTS(s) ({ 
*out++ = (int16_t)SAMPLE_CONV(s); 
if (AY8910_OUTPUT_STEREO) *out++ = (int16_t)SAMPLE_CONV(s); 
})
#define SAMPLE_CONV(f) (f * 65535.0f - 32768.0f)
#define AY8910_OUTPUT_STEREO
```

```c
#define OUT(s_) ({ 
int16_t s = (int16_t)(s_); 
*out++ = (int16_t)(s); 
})
```

--------------------------------

### rsp_opus_init

Source: https://libdragon.dev/ref/libopus__internal_8h_source

Initializes the Opus acceleration using the RSP.

```APIDOC
## rsp_opus_init

### Description
Initialize Opus RSP acceleration.

### Method
N/A (Function Signature)

### Endpoint
N/A (Internal Function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Console Initialization and Management

Source: https://libdragon.dev/ref/console_8c

Provides functions to initialize, close, clear, and render the console output.

```APIDOC
## Functions

### console_init

```markdown
void | console_init ()
```

**Description:** Initialize the console.

### console_close

```markdown
void | console_close ()
```

**Description:** Close the console.

### console_clear

```markdown
void | console_clear ()
```

**Description:** Clear the console.

### console_render

```markdown
void | console_render ()
```

**Description:** Render the console.

```

--------------------------------

### libdragon DMA Read Functions

Source: https://libdragon.dev/ref/dma_8h

Functions for reading data from peripherals using PI DMA. `dma_read_raw_async` starts an asynchronous read, `dma_read_async` starts an asynchronous read with higher-level abstractions, and `dma_read` performs a synchronous read, waiting for completion.

```c
void dma_read_raw_async(void *ram_address, unsigned long pi_address, unsigned long len);
void dma_read_async(void *ram_pointer, unsigned long pi_address, unsigned long len);
void dma_read(void *ram_address, unsigned long pi_address, unsigned long len);
```

--------------------------------

### Get Glyph Index by Codepoint (C)

Source: https://libdragon.dev/ref/rdpq__font_8h

Obtains the internal index for a glyph using its Unicode codepoint. This index is useful for further lookups like getting glyph metrics or verifying glyph existence. May return false positives for sparse ranges.

```c
int rdpq_font_get_glyph_index(const rdpq_font_t *_fnt_, uint32_t _codepoint_)
Get the internal index of a glyoh given the codepoint.
This function returns the internal index of a glyph given its unicode codepoint. The index can be used to perform further lookups (eg: get the metrics), or just to verify whether a glyph exists in the font or not.
When calling this query for a glyph that falls within a sparse range, false positives can be returned. That is, for a certain unicode codepoint within the range but that is not present in the font, this function might return a wrong index (actually referring to a different glyph). This happens because font64 does not store the codepoints for glyphs in sparse ranges, and querying a non existing glyph is considered undefined behavior.

Parameters
     fnt| Font to query
codepoint| Unicode codepoint of the glyph

Returns
    int Internal index of the glyph, or -1 if the glyph does not exist
```

--------------------------------

### Sample Buffer Macros

Source: https://libdragon.dev/ref/samplebuffer_8c

Defines for sample buffer tracing and formatted debugging output.

```APIDOC
## Sample Buffer Macros

### Description
Macros for controlling debug logging and formatted output related to the sample buffer.

### Method
#define

### Endpoints
- MIXER_TRACE
- tracef

### Parameters
#### MIXER_TRACE
- **value** (0 or 1) - Set to 1 to activate debug logs.

#### tracef
- **fmt** (const char *) - Format string for the message.
- **...** - Variable arguments for formatting.

### Request Example
```json
// MIXER_TRACE is a define, not called with parameters
// tracef is a macro, used directly in code
// Example usage:
// MIXER_TRACE = 1;
// tracef("Sample buffer event: %s", event_name);
```

### Response
#### Success Response (N/A)
- These are preprocessor macros and do not have runtime responses.

#### Response Example
```json
// N/A
```
```

--------------------------------

### Example Usage of RDPQ Debug Logging

Source: https://libdragon.dev/ref/rdpq__debug_8h

Demonstrates the usage of rdpq_debug_log and rdpq_debug_log_msg to log RDP commands for specific drawing operations. This example logs messages before and after drawing rectangles with different colors, showing how to isolate command sequences.

```c
rdpq_debug_log(true);
rdpq_debug_log_msg("Black rectangle");
rdpq_set_mode_fill(RGBA32(0,0,0,0));
rdpq_fill_rectangle(0, 0, 320, 120);
rdpq_debug_log_msg("Red rectangle");
rdpq_set_fill_color(RGBA32(255,0,0,0));
rdpq_fill_rectangle(120, 120, 320, 240);
rdpq_debug_log(false);
```

--------------------------------

### Initialize Audio Subsystem (C)

Source: https://libdragon.dev/ref/group__audio

Initializes the libdragon audio subsystem with a specified frequency and number of buffers. This function must be called before any other audio operations.

```c
void audio_init(const int frequency, int numbuffers);
```

--------------------------------

### RDPQ Initialization and Shutdown

Source: https://libdragon.dev/ref/rdpq_8c

Documents the `rdpq_init` and `rdpq_close` functions for initializing and shutting down the RDPQ library, respectively.

```APIDOC
## ◆ rdpq_init()

### Description
Initializes the RDPQ library. This function should be called by higher-level libraries using RDPQ or by the application's main function if it directly uses RDPQ functions. It is safe to call multiple times.

### Method
`void rdpq_init(void)`

## ◆ rdpq_close()

### Description
Shuts down the RDPQ library. Primarily intended for testing purposes.

### Method
`void rdpq_close(void)`
```

--------------------------------

### Libdragon Memory Boundary Declarations (C)

Source: https://libdragon.dev/ref/n64sys_8h_source

Declares external symbols that mark the boundaries of different memory sections within the libdragon executable. These include the start of the libdragon text section, the end of the ROM, and the end of the BSS section, which defines the start of the heap.

```c
extern char __libdragon_text_start[];

extern char __rom_end[];

extern char __bss_end[];

```

--------------------------------

### Console Initialization and Management Functions

Source: https://libdragon.dev/ref/console_8c

Provides functions to initialize, close, clear, and render the console. It also includes a function to set the rendering mode and a debug output option.

```c
void console_init ();
void console_close ();
void console_clear ();
void console_render ();
void console_set_render_mode (int mode);
void console_set_debug (bool debug);
```

--------------------------------

### Display Initialization and Management

Source: https://libdragon.dev/ref/display_8h

Functions for initializing, closing, and managing display buffers.

```APIDOC
## void display_init (resolution_t res, bitdepth_t bit, uint32_t num_buffers, gamma_t gamma, filter_options_t filters)

### Description
Initialize the display to a particular resolution and bit depth.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
display_init((resolution_t){320, 240}, DEPTH_16_BPP, 2, GAMMA_NONE, FILTERS_DISABLED);
```

### Response
#### Success Response (void)
N/A

#### Response Example
N/A

---

## void display_close ()

### Description
Close the display.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```c
display_close();
```

### Response
#### Success Response (void)
N/A

#### Response Example
N/A

---

## surface_t * display_get (void)

### Description
Get a display buffer for rendering.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```c
surface_t *buffer = display_get();
```

### Response
#### Success Response (surface_t *)
- **buffer** (surface_t *) - A pointer to the display surface for rendering.

#### Response Example
```json
{
  "buffer": "<pointer_to_surface>"
}
```

---

## surface_t * display_try_get (void)

### Description
Try getting a display surface. This function may return NULL if no surface is available.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```c
surface_t *buffer = display_try_get();
if (buffer) {
  // Render to buffer
}
```

### Response
#### Success Response (surface_t *)
- **buffer** (surface_t *) - A pointer to the display surface, or NULL if none is available.

#### Response Example
```json
{
  "buffer": "<pointer_to_surface_or_null>"
}
```

---

## void display_show (surface_t *surf)

### Description
Display a buffer on the screen.

### Method
N/A (Function Call)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```c
surface_t *my_surface = ...;
display_show(my_surface);
```

### Response
#### Success Response (void)
N/A

#### Response Example
N/A
```

--------------------------------

### Get Sprite Format (sprite_get_format)

Source: https://libdragon.dev/ref/sprite_8h

Retrieves the texture format of a given sprite.

```APIDOC
## Function: sprite_get_format()

### Description
Gets the sprite texture format.

### Method
GET

### Endpoint
sprite_get_format

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body

- **sprite** (sprite_t*) - Required - The sprite structure.

### Request Example
```c
sprite_t* my_sprite = sprite_load("rom:/my.sprite");
tex_format_t format = sprite_get_format(my_sprite);
```

### Response

#### Success Response (200)
- **tex_format_t** - The texture format of the sprite.

#### Response Example
```json
{
  "format": "FMT_RGBA16"
}
```
```

--------------------------------

### Initialize Audio Subsystem (C)

Source: https://libdragon.dev/ref/audio_8h_source

Initializes the audio subsystem with a specified frequency and number of buffers. This function must be called before using other audio functions.

```c
#include <libdragon.h>

// Example usage:
int frequency = 44100;
int num_buffers = 4;
audio_init(frequency, num_buffers);
```

--------------------------------

### DragonFS File Operations (C)

Source: https://libdragon.dev/ref/dragonfs_8h_source

Provides C functions for interacting with the DragonFS file system. These functions allow initialization, opening, reading, seeking, closing, checking for end-of-file, and getting file sizes. It also includes a function to get the ROM address and size of a file, and to translate error codes to strings.

```c
int dfs_init(uint32_t base_fs_loc);

int dfs_open(const char * const path);

int dfs_read(void * const buf, int size, int count, uint32_t handle);

int dfs_seek(uint32_t handle, int offset, int origin);

int dfs_tell(uint32_t handle);

int dfs_close(uint32_t handle);

int dfs_eof(uint32_t handle);

int dfs_size(uint32_t handle);

uint32_t dfs_rom_addr(const char *path);

int dfs_rom_size(const char *path);

const char *dfs_strerror(int error);
```

--------------------------------

### Joypad Initialization and Closing

Source: https://libdragon.dev/ref/joypad_8h_source

Functions to initialize and close the Joypad subsystem.

```APIDOC
## Joypad Initialization and Closing

### Description
Functions to initialize and close the Joypad subsystem.

### Initialize Joypad Subsystem

#### Method
`void joypad_init(void)`

#### Endpoint
N/A (Function call)

### Close Joypad Subsystem

#### Method
`void joypad_close(void)`

#### Endpoint
N/A (Function call)
```

--------------------------------

### Timer Tick Management

Source: https://libdragon.dev/ref/timer_8h

Functions to get the current timer ticks and convert between microseconds and ticks.

```APIDOC
## Timer Tick Management

### Description
Functions to get the current timer ticks and convert between microseconds and ticks.

### Functions

#### `timer_ticks`
* **Description**: Return total ticks since timer was initialized, as a 64-bit counter.
* **Method**: long long
* **Endpoint**: N/A
```

--------------------------------

### Timer Control

Source: https://libdragon.dev/ref/timer_8h_source

Functions to start, stop, restart, and delete timers.

```APIDOC
## Timer Control API

### Description
Provides functions to manage the lifecycle of timer links, including starting, stopping, restarting, and deleting them.

### Endpoints

#### `start_timer(timer, ticks, flags, callback)`

##### Description
Starts or restarts a timer with new parameters.

##### Method
`void`

##### Parameters
*   `timer` (timer_link_t *) - The timer link to start.
*   `ticks` (int) - The number of ticks before the timer expires.
*   `flags` (int) - Timer flags (e.g., `TF_ONE_SHOT`, `TF_CONTINUOUS`).
*   `callback` (timer_callback1_t) - The callback function to be executed when the timer expires.

#### `start_timer_context(timer, ticks, flags, callback, ctx)`

##### Description
Starts or restarts a timer with a context parameter for the callback function.

##### Method
`void`

##### Parameters
*   `timer` (timer_link_t *) - The timer link to start.
*   `ticks` (int) - The number of ticks before the timer expires.
*   `flags` (int) - Timer flags (e.g., `TF_ONE_SHOT`, `TF_CONTINUOUS`).
*   `callback` (timer_callback2_t) - The callback function to be executed when the timer expires, accepting a context.
*   `ctx` (void *) - The context pointer to be passed to the callback function.

#### `restart_timer(timer)`

##### Description
Restarts an existing timer with its previously set parameters.

##### Method
`void`

##### Parameters
*   `timer` (timer_link_t *) - The timer link to restart.

#### `stop_timer(timer)`

##### Description
Stops a running timer.

##### Method
`void`

##### Parameters
*   `timer` (timer_link_t *) - The timer link to stop.

#### `delete_timer(timer)`

##### Description
Deletes a timer link and releases its resources. It's recommended to stop the timer before deleting it.

##### Method
`void`

##### Parameters
*   `timer` (timer_link_t *) - The timer link to delete.
```

--------------------------------

### Enumerations - g

Source: https://libdragon.dev/ref/globals_eval_g

Lists documented enum values starting with 'g', along with their corresponding header files.

```APIDOC
## Enumerations - g

### Description
Lists documented enum values starting with 'g', along with their corresponding header files.

### Method
N/A (Documentation Listing)

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **enum_value** (string) - The name of the enumeration value.
- **header_file** (string) - The header file where the enumeration value is defined.

#### Response Example
{
  "enum_value": "GAMMA_CORRECT",
  "header_file": "display.h"
}
```

--------------------------------

### Console Initialization and Closing

Source: https://libdragon.dev/ref/console_8h_source

Functions to initialize and close the libdragon console. `console_init` prepares the console for use, while `console_close` releases associated resources.

```c
#ifndef __LIBDRAGON_CONSOLE_H
#define __LIBDRAGON_CONSOLE_H

#include <stdbool.h>
#include "display.h"

// ... other definitions ...

void console_init();
void console_close();

// ... other definitions ...

#endif
```

--------------------------------

### ym64player_tell

Source: https://libdragon.dev/ref/ym64_8c

Gets the current playback position of the YM module, returning the position in ticks and/or seconds.

```APIDOC
## ym64player_tell()

### Description
Reads the current playback position of the YM module. The position is returned in ticks (internal YM position) and as the number of seconds. You can pass `NULL` for information you are not interested in.

### Method
GET (or similar, depending on context)

### Endpoint
N/A (Function call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
int current_pos_ticks;
float current_secs;
ym64player_tell(player, &current_pos_ticks, &current_secs);
```

### Response
#### Success Response (Return Value)
- **pos** (int *) - Pointer to store the current position in ticks. Can be NULL.
- **secs** (float *) - Pointer to store the current position in seconds. Can be NULL.

#### Response Example
(No direct JSON response for this C function, values are returned via pointers)

Example usage result:
`current_pos_ticks` might be `6789`
`current_secs` might be `30.2`
```

--------------------------------

### RDPQ Initialization and Cleanup Functions (C)

Source: https://libdragon.dev/ref/rdpq_8h_source

Declares functions for initializing and closing the RDPQ system. `rdpq_init()` is used to set up the RDPQ, and `rdpq_close()` performs necessary cleanup.

```c
extern void __rdpq_set_scissor(uint32_t, uint32_t);

void rdpq_init(void);

void rdpq_close(void);
```

--------------------------------

### Identify Port Command

Source: https://libdragon.dev/ref/group__joybus__commands

Structure for the Identify Port Joybus command, used to get device information.

```APIDOC
## Identify Port Command

### Description
Identifies a connected Joybus device and retrieves its status.

### Method
Not applicable (struct definition)

### Endpoint
Not applicable (struct definition)

### Parameters
#### Send Data Structure (`joybus_cmd_identify_port_t.send`)
- **command** (uint8_t) - Required - Joybus command ID (JOYBUS_COMMAND_ID_IDENTIFY).

#### Receive Data Structure (`joybus_cmd_identify_port_t.recv`)
- **identifier** (uint16_t) - Required - Joybus device identifier.
- **status** (uint8_t) - Required - Joybus device status byte.

### Request Example
```json
{
  "command": "JOYBUS_COMMAND_ID_IDENTIFY"
}
```

### Response
#### Success Response
- **identifier** (uint16_t) - The unique identifier of the Joybus device.
- **status** (uint8_t) - The current status of the Joybus device.

#### Response Example
```json
{
  "identifier": 1024,
  "status": 0
}
```
```

--------------------------------

### AY8910 Initialization and Configuration Functions

Source: https://libdragon.dev/ref/ay8910_8h_source

Provides functions to reset the AY8910 emulator, set up I/O port read/write callbacks, and write to the chip's address register. These are essential for integrating the AY8910 emulator into an application.

```c
void ay8910_reset(AY8910 *ay);
void ay8910_set_ports(AY8910 *ay, uint8_t (*PortRead)(int), void (*PortWrite)(int, uint8_t));
void ay8910_write_addr(AY8910 *ay, uint8_t addr);
```

--------------------------------

### Console Initialization and Closing Functions

Source: https://libdragon.dev/ref/console_8h

Provides functions to initialize and close the console. `console_init()` sets up the console, and `console_close()` cleans up resources.

```c
void console_init ();
void console_close ();
```

--------------------------------

### EEPROM Filesystem Initialization and Closing (C)

Source: https://libdragon.dev/ref/eepromfs_8h_source

Initializes the EEPROM filesystem with provided entries and closes it. eepfs_init takes an array of eepfs_entry_t structures and their count, while eepfs_close de-initializes the filesystem.

```c
#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

// ... other includes and definitions ...

int eepfs_init(const eepfs_entry_t * entries, size_t count);
int eepfs_close(void);
```

--------------------------------

### decompress_lz4_reset

Source: https://libdragon.dev/ref/lz4__dec__internal_8h

Resets the state of an initialized LZ4 decompressor, allowing it to start decompressing from the beginning of the stream again.

```APIDOC
## decompress_lz4_reset()

### Description
Reset the LZ4 decompressor state. This function allows re-initializing the decompressor state, typically used to restart decompression from the beginning of the data stream.

### Method
N/A (Function Signature)

### Endpoint
N/A (Function Signature)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
void decompress_lz4_reset(void * _state);
```

### Response
#### Success Response (200)
None (void function)

#### Response Example
None
```

--------------------------------

### Sprite Tile and Texture Information

Source: https://libdragon.dev/ref/sprite_8c

Functions to access individual tiles within a sprite, get texture parameters, and determine LOD count.

```APIDOC
## sprite_get_tile

### Description
Return a surface_t pointing to a specific tile of the spritemap.

### Method
GET

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
sprite_t *my_sprite = sprite_load("path/to/spritemap.spr");
surface_t tile_surface = sprite_get_tile(my_sprite, 2, 3); // Get tile at horizontal index 2, vertical index 3
// Use tile_surface
```

### Response
#### Success Response (200)
- **surface_t** - A surface_t structure representing the specified tile's pixel data.

#### Response Example
```json
{
  "surface_info": {
    "width": 16,
    "height": 16,
    "format": "RGBA32",
    "data_ptr": "0x11223344"
  }
}
```

## sprite_get_texparms

### Description
Get a copy of the RDP texparms, optionally stored within the sprite.

### Method
GET

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
sprite_t *my_sprite = sprite_load("path/to/sprite.spr");
rdpq_texparms_t tex_parms;
bool success = sprite_get_texparms(my_sprite, &tex_parms);
if (success) {
    // Use the populated tex_parms structure
}
```

### Response
#### Success Response (200)
- **bool** - True if texparms were retrieved successfully, false otherwise.
- **rdpq_texparms_t** - The retrieved texture parameters.

#### Response Example
```json
{
  "retrieved": true,
  "texture_parms": {
    "							s/t addresses": "MIRROR",
    "							lod_bias": 1.5
  }
}
```

## sprite_get_lod_count

### Description
Return the number of LOD levels stored within the sprite (including the main image).

### Method
GET

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
sprite_t *my_sprite = sprite_load("path/to/sprite.spr");
int lod_count = sprite_get_lod_count(my_sprite);
// lod_count will be >= 1
```

### Response
#### Success Response (200)
- **int** - The number of LOD levels in the sprite.

#### Response Example
```json
{
  "lod_levels": 4
}
```

## sprite_get_format

### Description
Get the sprite's texture format.

### Method
GET

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
sprite_t *my_sprite = sprite_load("path/to/sprite.spr");
tex_format_t format = sprite_get_format(my_sprite);
// Use the format enum value
```

### Response
#### Success Response (200)
- **tex_format_t** - The enumeration value representing the sprite's texture format.

#### Response Example
```json
{
  "texture_format": "RGBA16"
}
```
```

--------------------------------

### Joypad Initialization and Management

Source: https://libdragon.dev/ref/group__joypad

Functions for initializing, closing, and polling the Joypad subsystem, as well as checking controller connectivity.

```APIDOC
## Joypad Initialization and Management

### `joypad_init()`

**Description**: Initialize the Joypad subsystem.

**Method**: void

### `joypad_close()`

**Description**: Close the Joypad subsystem.

**Method**: void

### `joypad_poll()`

**Description**: Fetch the current Joypad input state.

**Method**: void

### `joypad_is_connected(joypad_port_t port)`

**Description**: Check if a Joybus device is plugged in to a Joypad port.

**Method**: bool

**Parameters**:

#### Path Parameters
- **port** (joypad_port_t) - Required - The Joypad port to check.
```

--------------------------------

### Macros

Source: https://libdragon.dev/ref/system_8h

Constants defining limits for filesystems and open handles.

```APIDOC
## Macros

### `MAX_FILESYSTEMS`

**Description:** Number of filesystems that can be attached to the system.

**Value:** 10

### `MAX_OPEN_HANDLES`

**Description:** Number of open handles that can be maintained at one time.

**Value:** 4096
```

--------------------------------

### Sample Buffer Data Access

Source: https://libdragon.dev/ref/samplebuffer_8c

Functions for accessing and manipulating sample data within the buffer, including getting, appending, and undoing samples.

```APIDOC
## Sample Buffer Data Access Functions

### Description
These functions provide methods to access and modify the sample data within a buffer using a zero-copy approach. You can retrieve pointers to sample data, append new samples, and remove samples from the tail.

### Method
void* / void

### Endpoints
- samplebuffer_get
- samplebuffer_append
- samplebuffer_undo
- samplebuffer_discard
- samplebuffer_flush

### Parameters
#### samplebuffer_get
- **buf** (samplebuffer_t *) - Required - The sample buffer.
- **wpos** (int) - Required - The write position to get samples from.
- **wlen** (int *) - Required - Pointer to store the length of the retrieved samples.

#### samplebuffer_append
- **buf** (samplebuffer_t *) - Required - The sample buffer.
- **wlen** (int) - Required - The number of samples to append.

#### samplebuffer_undo
- **buf** (samplebuffer_t *) - Required - The sample buffer.
- **wlen** (int) - Required - The number of samples to remove from the tail.

#### samplebuffer_discard
- **buf** (samplebuffer_t *) - Required - The sample buffer.
- **wpos** (int) - Required - The write position to discard samples up to.

#### samplebuffer_flush
- **buf** (samplebuffer_t *) - Required - The sample buffer.

### Request Example
```json
// Example for samplebuffer_get
{
  "buf": "samplebuffer_t*",
  "wpos": 100,
  "wlen": "int*"
}

// Example for samplebuffer_append
{
  "buf": "samplebuffer_t*",
  "wlen": 50
}

// Example for samplebuffer_undo
{
  "buf": "samplebuffer_t*",
  "wlen": 20
}

// Example for samplebuffer_discard
{
  "buf": "samplebuffer_t*",
  "wpos": 75
}

// Example for samplebuffer_flush (no body needed)
```

### Response
#### Success Response (200)
- **samplebuffer_get**: void* - Pointer to the requested samples.
- **samplebuffer_append**: void - No return value.
- **samplebuffer_undo**: void - No return value.
- **samplebuffer_discard**: void - No return value.
- **samplebuffer_flush**: void - No return value.

#### Response Example
```json
// Example for samplebuffer_get
{
  "samples_ptr": "void*"
}

// No response body for void functions
```
```

--------------------------------

### Sample Buffer Initialization (C)

Source: https://libdragon.dev/ref/samplebuffer_8h

Initializes a sample buffer structure with provided memory and size. This function sets up the necessary internal state for storing and managing audio samples.

```c
void samplebuffer_init (samplebuffer_t *buf, uint8_t *uncached_mem, int size)
```

--------------------------------

### rdpq_set_mode_standard

Source: https://libdragon.dev/ref/rdpq__mode_8h_source

Sets the RDPQ rendering mode to a standard configuration. This is a basic setup for typical rendering operations.

```APIDOC
## rdpq_set_mode_standard

### Description
Sets the RDPQ rendering mode to a standard configuration.

### Method
void

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (void)
N/A

#### Response Example
N/A
```
Tokens:
Raw