### Create and Use Hash Tables with MTY_HashCreate

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Demonstrates creating and managing a hash table for key/value storage using string or integer keys. Includes examples of setting, getting, iterating, and removing elements. Remember to free allocated data and destroy the hash table.

```c
#include "matoya.h"

typedef struct {
    char name[64];
    int value;
} UserData;

void hash_example(void)
{
    // Create hash table with default bucket count
    MTY_Hash *hash = MTY_HashCreate(0);

    // Store data by string key
    UserData *user1 = MTY_Alloc(1, sizeof(UserData));
    snprintf(user1->name, sizeof(user1->name), "Alice");
    user1->value = 100;
    MTY_HashSet(hash, "user_alice", user1);

    UserData *user2 = MTY_Alloc(1, sizeof(UserData));
    snprintf(user2->name, sizeof(user2->name), "Bob");
    user2->value = 200;
    MTY_HashSet(hash, "user_bob", user2);

    // Store data by integer key
    UserData *user3 = MTY_Alloc(1, sizeof(UserData));
    snprintf(user3->name, sizeof(user3->name), "Charlie");
    user3->value = 300;
    MTY_HashSetInt(hash, 12345, user3);

    // Retrieve by string key
    UserData *found = MTY_HashGet(hash, "user_alice");
    if (found) {
        MTY_Log("Found: %s = %d", found->name, found->value);
    }

    // Retrieve by integer key
    found = MTY_HashGetInt(hash, 12345);
    if (found) {
        MTY_Log("Found by int key: %s = %d", found->name, found->value);
    }

    // Iterate all string keys
    const char *key;
    uint64_t iter = 0;
    while (MTY_HashGetNextKey(hash, &iter, &key)) {
        UserData *data = MTY_HashGet(hash, key);
        MTY_Log("Key '%s': name=%s, value=%d", key, data->name, data->value);
    }

    // Remove and get item
    UserData *removed = MTY_HashPop(hash, "user_bob");
    if (removed) {
        MTY_Log("Removed: %s", removed->name);
        MTY_Free(removed);
    }

    // Destroy hash with custom free function
    MTY_HashDestroy(&hash, MTY_Free);
}
```

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

### Get Platform Information

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetPlatform

Retrieves the current platform and version information.

```APIDOC
## GET MTY_GetPlatform

### Description
Get the current platform.

### Method
GET

### Endpoint
/MTY_GetPlatform

### Return Value
- **uint32_t** - An `MTY_OS` value bitwise OR'd with the OS's major and minor version numbers. The major version has a mask of `0xFF00` and the minor has a mask of `0xFF`. On Android, only a single version number is reported, the API level, in the position of the major number.

### Supported Platforms
- Windows
- macOS
- Android
- Linux
- Web
```

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

### MTY_HashCreate - Hash Table Example

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Demonstrates the creation and use of a hash table for efficient key-value storage and retrieval.

```APIDOC
## MTY_HashCreate

Creates a hash table for efficient key/value lookup using string or integer keys.

### Description
This function initializes a hash table data structure that allows for fast insertion, retrieval, and deletion of data based on keys. It supports both string and integer keys.

### Method
`MTY_HashCreate`

### Parameters
- `buckets` (uint32_t) - The initial number of buckets in the hash table. If 0, a default value is used.

### Return Value
- `MTY_Hash*` - A pointer to the newly created hash table object. Returns NULL on failure.

### Example Usage (C)
```c
#include "matoya.h"

typedef struct {
    char name[64];
    int value;
} UserData;

void hash_example(void)
{
    // Create hash table with default bucket count
    MTY_Hash *hash = MTY_HashCreate(0);

    // Store data by string key
    UserData *user1 = MTY_Alloc(1, sizeof(UserData));
    snprintf(user1->name, sizeof(user1->name), "Alice");
    user1->value = 100;
    MTY_HashSet(hash, "user_alice", user1);

    UserData *user2 = MTY_Alloc(1, sizeof(UserData));
    snprintf(user2->name, sizeof(user2->name), "Bob");
    user2->value = 200;
    MTY_HashSet(hash, "user_bob", user2);

    // Store data by integer key
    UserData *user3 = MTY_Alloc(1, sizeof(UserData));
    snprintf(user3->name, sizeof(user3->name), "Charlie");
    user3->value = 300;
    MTY_HashSetInt(hash, 12345, user3);

    // Retrieve by string key
    UserData *found = MTY_HashGet(hash, "user_alice");
    if (found) {
        MTY_Log("Found: %s = %d", found->name, found->value);
    }

    // Retrieve by integer key
    found = MTY_HashGetInt(hash, 12345);
    if (found) {
        MTY_Log("Found by int key: %s = %d", found->name, found->value);
    }

    // Iterate all string keys
    const char *key;
    uint64_t iter = 0;
    while (MTY_HashGetNextKey(hash, &iter, &key)) {
        UserData *data = MTY_HashGet(hash, key);
        MTY_Log("Key '%s': name=%s, value=%d", key, data->name, data->value);
    }

    // Remove and get item
    UserData *removed = MTY_HashPop(hash, "user_bob");
    if (removed) {
        MTY_Log("Removed: %s", removed->name);
        MTY_Free(removed);
    }

    // Destroy hash with custom free function
    MTY_HashDestroy(&hash, MTY_Free);
}
```

### Related Functions
- `MTY_HashSet`
- `MTY_HashSetInt`
- `MTY_HashGet`
- `MTY_HashGetInt`
- `MTY_HashGetNextKey`
- `MTY_HashPop`
- `MTY_HashDestroy`
- `MTY_Alloc`, `MTY_Free`
```

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

### Build libmatoya on Windows

Source: https://github.com/snowcone-ltd/libmatoya/wiki/Building

Use the nmake command to build libmatoya on Windows. Ensure you have the necessary build tools installed.

```shell
nmake
```

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

### Start libmatoya Web App

Source: https://github.com/snowcone-ltd/libmatoya/wiki/Building

Call MTY_Start with the path to your compiled WebAssembly binary, a DOM element for the canvas, and optional user-defined functions.

```javascript
MTY_Start(bin, container, userEnv)
```

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

### Get Application Icon

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetProgramIcon

Call this function with the path to an application binary to get its icon. The width and height of the icon will be set in the provided pointers. The returned buffer must be freed with MTY_Free.

```C
void *MTY_GetProgramIcon(
    const char * path,
    uint32_t *   width,
    uint32_t *   height
);
```

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

### Get Process Path (C)

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetProcessPath

Call this function to get the full path of the current process. The returned buffer is thread-local and should not be freed.

```C
const char *MTY_GetProcessPath(void);
```

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

### MTY_ThreadCreate - Thread Creation Example

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Demonstrates how to create and manage threads using MTY_ThreadCreate, including synchronization with mutexes and condition variables.

```APIDOC
## MTY_ThreadCreate

Creates a thread that executes a function asynchronously with proper cross-platform support.

### Description
This function creates a new thread of execution that runs a specified function. It is designed for cross-platform compatibility.

### Method
`MTY_ThreadCreate`

### Parameters
- `worker_thread` (function pointer) - The function to be executed by the new thread.
- `opaque` (void*) - A pointer to data that will be passed to the `worker_thread` function.

### Return Value
- `MTY_Thread*` - A pointer to the newly created thread object. Returns NULL on failure.

### Example Usage (C)
```c
#include "matoya.h"

typedef struct {
    MTY_Mutex *mutex;
    MTY_Cond *cond;
    int counter;
    bool done;
} SharedData;

static void *worker_thread(void *opaque)
{
    SharedData *data = (SharedData *)opaque;

    for (int i = 0; i < 10; i++) {
        MTY_MutexLock(data->mutex);
        data->counter++;
        MTY_Log("Worker: counter = %d", data->counter);
        MTY_MutexUnlock(data->mutex);

        MTY_Sleep(100);  // Sleep 100ms
    }

    MTY_MutexLock(data->mutex);
    data->done = true;
    MTY_CondSignal(data->cond);
    MTY_MutexUnlock(data->mutex);

    return NULL;
}

void threading_example(void)
{
    SharedData data = {
        .mutex = MTY_MutexCreate(),
        .cond = MTY_CondCreate(),
        .counter = 0,
        .done = false
    };

    // Create worker thread
    MTY_Thread *thread = MTY_ThreadCreate(worker_thread, &data);

    // Wait for completion using condition variable
    MTY_MutexLock(data.mutex);
    while (!data.done) {
        MTY_CondWait(data.cond, data.mutex, 1000);  // 1 second timeout
        MTY_Log("Main: waiting, counter = %d", data.counter);
    }
    MTY_MutexUnlock(data.mutex);

    // Wait for thread to finish and get return value
    void *ret = MTY_ThreadDestroy(&thread);
    MTY_Log("Thread completed, final counter = %d", data.counter);

    MTY_CondDestroy(&data.cond);
    MTY_MutexDestroy(&data.mutex);
}
```

### Related Functions
- `MTY_MutexCreate`, `MTY_MutexLock`, `MTY_MutexUnlock`
- `MTY_CondCreate`, `MTY_CondSignal`, `MTY_CondWait`
- `MTY_Sleep`
- `MTY_ThreadDestroy`
```

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

### C System and OS Interaction Example

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Shows how to retrieve platform information, process details, hostname, and interact with the operating system like opening URLs or loading dynamic libraries. Ensure the shared library path and symbol names are correct.

```c
#include "matoya.h"

void system_example(void)
{
    // Get current platform
    MTY_OS platform = MTY_GetPlatform();
    MTY_Log("Platform: %s", MTY_GetPlatformString(platform));

    // Check if libmatoya is supported
    if (MTY_IsSupported()) {
        MTY_Log("libmatoya is fully supported on this platform");
    }

    // Get process information
    MTY_Log("Process path: %s", MTY_GetProcessPath());
    MTY_Log("Process dir: %s", MTY_GetProcessDir());

    // Get hostname
    char hostname[256];
    MTY_GetHostname(hostname, sizeof(hostname));
    MTY_Log("Hostname: %s", hostname);

    // Open URL in default browser
    MTY_HandleProtocol("https://github.com/matoya/libmatoya");

    // Get shared object extension
    MTY_Log("Shared object extension: %s", MTY_GetSOExtension());

    // Load shared library dynamically
    MTY_SO *lib = MTY_SOLoad("libm.so");  // Linux example
    if (lib) {
        // Get function pointer
        double (*my_sin)(double) = MTY_SOGetSymbol(lib, "sin");
        if (my_sin) {
            MTY_Log("sin(1.0) = %f", my_sin(1.0));
        }
        MTY_SOUnload(&lib);
    }

    // Set crash handler
    MTY_SetCrashFunc(NULL, NULL);  // Custom crash handling

    // Open console for debugging (Windows)
    MTY_OpenConsole("Debug Console");

    // Run on startup
    MTY_SetRunOnStartup("MyApp", MTY_GetProcessPath());
    if (MTY_GetRunOnStartup("MyApp")) {
        MTY_Log("App is set to run on startup");
    }
}

```

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

### Hotkey Management

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/App

Functions for setting, getting, and removing hotkeys.

```APIDOC
## MTY_AppGetHotkey

### Description
Get a previously set hotkey's `id`.

### Method
N/A (Function call)

### Endpoint
N/A

## MTY_AppSetHotkey

### Description
Set a hotkey combination.

### Method
N/A (Function call)

### Endpoint
N/A

## MTY_AppRemoveHotkeys

### Description
Remove all hotkeys.

### Method
N/A (Function call)

### Endpoint
N/A

## MTY_AppEnableGlobalHotkeys

### Description
Temporarily enable or disable the currently set globally scoped hotkeys.

### Method
N/A (Function call)

### Endpoint
N/A
```

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

### C Custom Logging Callback Example

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Demonstrates how to set up a custom logging function to handle log messages, including timestamping and writing to a file. Ensure the log file is properly opened and closed.

```c
#include "matoya.h"
#include <stdio.h>
#include <time.h>

// Custom log handler
static void my_log_func(const char *msg, void *opaque)
{
    FILE *log_file = (FILE *)opaque;

    time_t now = time(NULL);
    char timestamp[32];
    strftime(timestamp, sizeof(timestamp), "%Y-%m-%d %H:%M:%S", localtime(&now));

    fprintf(log_file, "[%s] %s\n", timestamp, msg);
    fflush(log_file);

    // Also print to console
    printf("[%s] %s\n", timestamp, msg);
}

void logging_example(void)
{
    // Open log file
    FILE *log_file = fopen("app.log", "a");

    // Set custom log callback
    MTY_SetLogFunc(my_log_func, log_file);

    // Now all MTY_Log calls go to our handler
    MTY_Log("Application started");
    MTY_Log("Version: %s", MTY_VERSION_STRING);

    // Get the most recent log message on current thread
    const char *last_log = MTY_GetLog();
    printf("Last log: %s\n", last_log);

    // Temporarily disable logging
    MTY_DisableLog(true);
    MTY_Log("This won't be logged");
    MTY_DisableLog(false);

    // Fatal log (logs message then calls abort)
    // MTY_LogFatal("Fatal error: %s", "something bad");  // Would terminate

    fclose(log_file);
}

```

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

### MTY_QueueCreate - Thread-Safe Queue Example

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Illustrates the creation and usage of a thread-safe queue for inter-thread communication.

```APIDOC
## MTY_QueueCreate

Creates a thread-safe multi-producer single-consumer queue for passing data between threads.

### Description
This function initializes a queue that can safely handle multiple producers adding data and a single consumer removing data. It is useful for decoupling tasks between threads.

### Method
`MTY_QueueCreate`

### Parameters
- `capacity` (size_t) - The maximum number of items the queue can hold.
- `itemSize` (size_t) - The size of each item to be stored in the queue.

### Return Value
- `MTY_Queue*` - A pointer to the newly created queue object. Returns NULL on failure.

### Example Usage (C)
```c
#include "matoya.h"

typedef struct {
    int id;
    char message[64];
} WorkItem;

void queue_example(void)
{
    // Create queue with 16 slots, each can hold a WorkItem
    MTY_Queue *queue = MTY_QueueCreate(16, sizeof(WorkItem));

    // Producer: get input buffer, fill it, push
    WorkItem *item = MTY_QueueGetInputBuffer(queue);
    if (item) {
        item->id = 1;
        snprintf(item->message, sizeof(item->message), "Hello from producer");
        MTY_QueuePush(queue, sizeof(WorkItem));
    }

    // Add more items
    for (int i = 2; i <= 5; i++) {
        item = MTY_QueueGetInputBuffer(queue);
        if (item) {
            item->id = i;
            snprintf(item->message, sizeof(item->message), "Message %d", i);
            MTY_QueuePush(queue, sizeof(WorkItem));
        }
    }

    MTY_Log("Queue length: %u", MTY_QueueGetLength(queue));

    // Consumer: get output buffer, process, pop
    size_t size;
    WorkItem *output;
    while ((output = MTY_QueueGetOutputBuffer(queue, &size)) != NULL) {
        MTY_Log("Received: id=%d, message='%s'", output->id, output->message);
        MTY_QueuePop(queue);
    }

    MTY_QueueDestroy(&queue);
}
```

### Related Functions
- `MTY_QueueGetInputBuffer`
- `MTY_QueuePush`
- `MTY_QueueGetOutputBuffer`
- `MTY_QueuePop`
- `MTY_QueueGetLength`
- `MTY_QueueDestroy`
```

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

### C Memory Allocation and String Operations Example

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Demonstrates memory allocation, reallocation, duplication, string manipulation, and secure memory operations. Ensure proper cleanup of allocated memory.

```c
#include "matoya.h"

void memory_example(void)
{
    // Allocate zeroed memory (never returns NULL, aborts on failure)
    int *numbers = MTY_Alloc(100, sizeof(int));
    for (int i = 0; i < 100; i++) {
        numbers[i] = i;
    }

    // Reallocate
    numbers = MTY_Realloc(numbers, 200, sizeof(int));

    // Duplicate buffer
    int *copy = MTY_Dup(numbers, 200 * sizeof(int));

    // Duplicate string
    char *str = MTY_Strdup("Hello, World!");

    // String concatenation (reallocates)
    str = MTY_Strcat(str, " More text!");
    MTY_Log("Concatenated: %s", str);

    // Formatted string (dynamically allocated)
    char *formatted = MTY_SprintfD("Value: %d, Name: %s", 42, "test");
    MTY_Log("Formatted: %s", formatted);

    // Case-insensitive comparison
    if (MTY_Strcasecmp("Hello", "HELLO") == 0) {
        MTY_Log("Strings match (case-insensitive)");
    }

    // Case-insensitive substring search
    const char *found = MTY_Strcasestr("Hello World", "WORLD");
    if (found) {
        MTY_Log("Found substring at: %s", found);
    }

    // Secure zeroing (prevents compiler optimization)
    char password[] = "secret123";
    MTY_SecureZero(password, sizeof(password));

    // Secure free (zeros then frees)
    char *sensitive = MTY_Strdup("sensitive data");
    MTY_SecureFree(sensitive, strlen(sensitive) + 1);

    // Endian conversion
    uint32_t value = 0x12345678;
    uint32_t swapped = MTY_Swap32(value);
    uint32_t big_endian = MTY_SwapToBE32(value);
    MTY_Log("Original: 0x%08X, Swapped: 0x%08X, BE: 0x%08X",
        value, swapped, big_endian);

    // Cleanup
    MTY_Free(numbers);
    MTY_Free(copy);
    MTY_Free(str);
    MTY_Free(formatted);
}

```

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

### Get Screen Size

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_WindowGetScreenSize

Retrieves the width and height of the screen where the window is currently located. Requires an MTY_App and MTY_Window as input.

```C
MTY_Size MTY_WindowGetScreenSize(
    MTY_App *  app,
    MTY_Window window
);
```

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

### Check if Application Runs on Startup

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetRunOnStartup

Use this function to determine if a specific application name is registered to launch automatically when the system starts. The application name must be previously set using MTY_SetRunOnStartup.

```C
bool MTY_GetRunOnStartup(
    const char * name
);
```

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

### Set Application to Run on Startup (C)

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_SetRunOnStartup

Use this function to register an application to run automatically on system startup. Provide a unique name, the executable path, and any necessary arguments. Set the path to NULL to remove the application from startup.

```C
void MTY_SetRunOnStartup(
    const char * name,
    const char * path,
    const char * args
);
```

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

### Get Window Frame

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_WindowGetFrame

Use this function to get the normalized size and position of a window. It accounts for scaling and can be used to restore window state.

```C
MTY_Frame MTY_WindowGetFrame(
    MTY_App *  app,
    MTY_Window window
);
```

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

### Create and Run a libmatoya Application

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

This snippet demonstrates the basic structure for creating a libmatoya application, setting up an event loop, and handling window events. It includes initialization, window creation, and the main application run loop.

```c
#include "matoya.h"

// Application state structure
typedef struct {
    bool running;
    int frame_count;
} AppState;

// Called once per message cycle
static bool app_func(void *opaque)
{
    AppState *state = (AppState *)opaque;
    return state->running;
}

// Called for each event sent to the app
static void event_func(const MTY_Event *evt, void *opaque)
{
    AppState *state = (AppState *)opaque;

    switch (evt->type) {
        case MTY_EVENT_CLOSE:
        case MTY_EVENT_QUIT:
            state->running = false;
            break;
        case MTY_EVENT_KEY:
            if (evt->key.key == MTY_KEY_ESCAPE && evt->key.pressed)
                state->running = false;
            break;
        default:
            break;
    }
}

int main(int argc, char **argv)
{
    AppState state = {.running = true, .frame_count = 0};

    // Create app with default flags
    MTY_App *app = MTY_AppCreate(0, app_func, event_func, &state);
    if (!app) {
        MTY_Log("Failed to create app: %s", MTY_GetLog());
        return 1;
    }

    // Create a window
    MTY_Window window = MTY_WindowCreate(app, "My Application", NULL, 0);
    if (window < 0) {
        MTY_Log("Failed to create window: %s", MTY_GetLog());
        MTY_AppDestroy(&app);
        return 1;
    }

    // Run the application event loop (blocks until app_func returns false)
    MTY_AppRun(app);

    // Cleanup
    MTY_AppDestroy(&app);
    return 0;
}

```

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

### Get Special Directory Path

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetDir

Call this function to get the path to a special directory. The returned pointer is to thread-local storage and must not be freed.

```C
const char *MTY_GetDir(
    MTY_Dir dir
);
```

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

### File Operations with libmatoya

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

Demonstrates basic file read, write, append, check existence, path manipulation, directory creation, file listing, copy, move, and delete operations using libmatoya helpers.

```c
#include "matoya.h"

void file_operations_example(void)
{
    // Write data to file
    const char *data = "Hello, libmatoya!";
    if (MTY_WriteFile("output.txt", data, strlen(data))) {
        MTY_Log("File written successfully");
    }

    // Read file contents
    size_t size;
    void *contents = MTY_ReadFile("output.txt", &size);
    if (contents) {
        // Contents is null-terminated, safe to use as string
        MTY_Log("Read %zu bytes: %s", size, (char *)contents);
        MTY_Free(contents);
    }

    // Append text to file
    MTY_AppendTextToFile("output.txt", "\nAppended line");

    // Write formatted text
    MTY_WriteTextFile("config.txt", "name=%s\nvalue=%d", "test", 42);

    // Check if file exists
    if (MTY_FileExists("output.txt")) {
        MTY_Log("File exists");
    }

    // Get special directories
    char path[MTY_PATH_MAX];
    MTY_JoinPath(MTY_GetDir(MTY_DIR_HOME), "myapp", path, MTY_PATH_MAX);
    MTY_Log("Home app path: %s", path);

    // Create directory (including parents)
    MTY_Mkdir(path);

    // Get file list
    MTY_FileList *list = MTY_GetFileList(".", false);  // Non-recursive
    if (list) {
        for (uint32_t i = 0; i < list->len; i++) {
            MTY_Log("  %s%s", list->files[i].name,
                list->files[i].dir ? "/" : "");
        }
        MTY_FreeFileList(&list);
    }

    // File copy and move
    MTY_CopyFile("output.txt", "output_backup.txt");
    MTY_MoveFile("output_backup.txt", "output_moved.txt");

    // Delete file
    MTY_DeleteFile("output_moved.txt");
}

```

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

### Get Queue Length

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_QueueGetLength

Call this function to get an approximate count of items currently in the queue. The count may not be exact if the queue is being modified concurrently.

```C
uint32_t MTY_QueueGetLength(
    MTY_Queue * ctx
);
```

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

### Get Platform Without Web

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetPlatformNoWeb

Use this function to get the current platform, excluding the web environment. It attempts to detect the actual OS even in browser contexts.

```C
uint32_t MTY_GetPlatformNoWeb(void);
```

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

### Get Platform String

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetPlatformString

Converts a platform integer into a human-readable string. The returned buffer is thread-local and should not be freed. Masks can be applied to the platform integer to omit specific components from the output string.

```C
const char *MTY_GetPlatformString(
    uint32_t platform
);
```

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

### MTY_JSONArrayGetLength

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_JSONArrayGetLength

Get the number of items in an `MTY_JSON` array.

```APIDOC
## MTY_JSONArrayGetLength

### Description
Get the number of items in an `MTY_JSON` array.

### Method
N/A (This is a C function, not an HTTP endpoint)

### Endpoint
N/A

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

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response (200)
N/A (This is a C function, not an HTTP endpoint)

#### Response Example
N/A

### C Function Signature
```c
uint32_t MTY_JSONArrayGetLength(
    const MTY_JSON * json
);
```

### Parameters
- **`json`** (`const MTY_JSON *`) - An `MTY_JSON` item to query.

### Return Value
- **`uint32_t`** - Number of items in an `MTY_JSON` array.

### Platform Support
- Windows
- macOS
- Android
- Linux
- Web

### See Also
- [Module: JSON](JSON)
```

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

### Get Libmatoya Version

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetVersion

Retrieves the version of libmatoya that was compiled.

```APIDOC
## GET MTY_GetVersion

### Description
Get the version `libmatoya` was compiled with.

### Method
GET

### Endpoint
/version

### Return value
#### Success Response (200)
- **version** (uint32_t) - The major and minor version numbers packed into a 32-bit integer. The major version has a mask of `0xFF00` and the minor has a mask of `0xFF`.

### Response Example
```json
{
  "version": 16777217 
}
```
```

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

### Build libmatoya on macOS/Linux

Source: https://github.com/snowcone-ltd/libmatoya/wiki/Building

Use the make command to build libmatoya on macOS and Linux systems. This is the standard build process for Unix-like environments.

```shell
make
```

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

### Get Device Orientation

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_AppGetOrientation

Retrieves the current orientation of the device.

```APIDOC
## GET /app/orientation

### Description
Get the device's orientation.

### Method
GET

### Endpoint
/app/orientation

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **orientation** (MTY_Orientation) - Device's orientation.

#### Response Example
```json
{
  "orientation": "landscape"
}
```
```

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

### MTY_SetRunOnStartup

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_SetRunOnStartup

Sets an application to run on system startup. This function is supported on Windows.

```APIDOC
## MTY_SetRunOnStartup

### Description
Set an application to run on system startup.

### Method
`void MTY_SetRunOnStartup(
    const char * name,
    const char * path,
    const char * args
);`

### Parameters
#### Path Parameters
- **name** (const char *) - Required - An arbitrary application name.
- **path** (const char *) - Required - Path to the executable that should be launched. May be `NULL` to remove the application from system startup.
- **args** (const char *) - Optional - Argument string for the executable specified in `path`. This may be multiple command line arguments separated by spaces. May be `NULL` if `path` is also `NULL`.

### Platform Support
- Windows

### See Also
- [Module: System](System)
```

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

### MTY_GetRunOnStartup

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetRunOnStartup

Checks if a registered application name is set to run on system startup.

```APIDOC
## MTY_GetRunOnStartup

### Description
Checks if a registered application name is set to run on system startup.

### Method
N/A (C function)

### Endpoint
N/A (C function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
// No direct request example for a C function call in this format.
// Example usage would involve calling the function within C code.
```

### Response
#### Success Response (bool)
- **return value** (bool) - Returns true if the application is set to run on startup, false otherwise.

#### Response Example
```json
{
  "example": "true or false"
}
```

### Platform Support
Windows
```

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

### Get High Precision Time Stamp

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/Time

Retrieves a high-precision timestamp.

```APIDOC
## MTY_GetTime

### Description
Get a high precision time stamp.

### Method
[Not specified, likely a function call]

### Endpoint
[Not applicable, this is a function]

### Parameters
None

### Request Example
```c
MTY_Time timestamp = MTY_GetTime();
```

### Response
#### Success Response
- **MTY_Time** (int64_t) - A high precision time stamp.
```

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

### Get Thread ID

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_ThreadGetID

Retrieves the unique identifier for a given thread context.

```APIDOC
## GET /api/threads/{id}

### Description
Retrieves the unique identifier for a given thread context.

### Method
GET

### Endpoint
/api/threads/{id}

### Parameters
#### Path Parameters
- **id** (MTY_Thread *) - Required - An MTY_Thread context.

### Response
#### Success Response (200)
- **id** (int64_t) - The thread's unique identifier.

### Response Example
```json
{
  "id": 1234567890
}
```
```

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

### Create a Custom libmatoya Window

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

This snippet shows how to create a libmatoya window with custom dimensions, position, and properties. It also demonstrates how to update the window title, set minimum size, retrieve its dimensions, and toggle fullscreen mode.

```c
#include "matoya.h"

void create_custom_window(MTY_App *app)
{
    // Create a frame with specific position and size
    MTY_Frame frame = {
        .x = 100,
        .y = 100,
        .w = 1280,
        .h = 720,
        .type = MTY_WINDOW_NORMAL
    };

    // Create window with custom frame
    MTY_Window window = MTY_WindowCreate(app, "Custom Window", &frame, 0);
    if (window < 0) {
        MTY_Log("Failed to create window");
        return;
    }

    // Set window properties
    MTY_WindowSetTitle(app, window, "Updated Title");
    MTY_WindowSetMinSize(app, window, 640, 480);

    // Get window dimensions
    uint32_t width, height;
    MTY_WindowGetSize(app, window, &width, &height);
    MTY_Log("Window size: %ux%u", width, height);

    // Make window fullscreen
    MTY_WindowSetFullscreen(app, window, true);
}

```

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

### Get Controller Type

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_AppGetControllerType

Retrieves the type of a specific controller using its ID.

```APIDOC
## GET MTY_AppGetControllerType

### Description
Get the type of controller.

### Method
GET

### Endpoint
/snowcone-ltd/libmatoya

### Parameters
#### Path Parameters
- **ctx** (MTY_App *) - Required - The MTY_App context.
- **id** (uint32_t) - Required - A controller id found via MTY_EVENT_CONTROLLER or MTY_EVENT_CONNECT.

### Response
#### Success Response (200)
- **MTY_CType** (MTY_CType) - The type of controller on success, MTY_CTYPE_DEFAULT if the controller does not exist or the controller type is not available.

### Platform Support
- Windows
- macOS
```

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

### Create MTY_App Instance

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_AppCreate

Use this function to create an MTY_App instance. It requires callback functions for application logic and event handling. Ensure to destroy the app instance with MTY_AppDestroy when it's no longer needed. Returns NULL on failure.

```C
MTY_App *MTY_AppCreate(
    MTY_AppFlag   flags,
    MTY_AppFunc   appFunc,
    MTY_EventFunc eventFunc,
    void *        opaque
);
```

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

### Get App Input Mode

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_AppGetInputMode

Retrieves the current mobile input mode of the application.

```APIDOC
## GET /app/input-mode

### Description
Get the app's current mobile input mode.

### Method
GET

### Endpoint
/app/input-mode

### Parameters
#### Path Parameters
- **ctx** (MTY_App *) - Required - The MTY_App context.

### Response
#### Success Response (200)
- **MTY_InputMode** (MTY_InputMode) - App's current mobile input mode.

### Response Example
```json
{
  "inputMode": "keyboard"
}
```
```

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

### Create MTY_Audio Context

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_AudioCreate

Initializes an audio playback context. Specify buffer sizes and channels. Device ID and fallback behavior are Windows-specific.

```C
MTY_Audio *MTY_AudioCreate(
    uint32_t     sampleRate,
    uint32_t     minBuffer,
    uint32_t     maxBuffer,
    uint8_t      channels,
    const char * deviceID,
    bool         fallback
);
```

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

### Get Controller Device Name

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_AppGetControllerDeviceName

Retrieves the device name of a controller using its ID.

```APIDOC
## GET /api/controllers/{id}/device-name

### Description
Get the device name of a controller.

### Method
GET

### Endpoint
/api/controllers/{id}/device-name

### Parameters
#### Path Parameters
- **id** (uint32_t) - Required - A controller id found via MTY_EVENT_CONTROLLER or MTY_EVENT_CONNECT.

### Response
#### Success Response (200)
- **device_name** (const char *) - The device name of the controller on success, NULL if the controller does not exist or the controller's device name is not available.

### Request Example
(No request body for GET request)

### Response Example
{
  "device_name": "Example Controller Name"
}
```

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

### App Module - Application and Window Management

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

APIs for creating and managing applications and windows.

```APIDOC
## MTY_AppCreate

### Description
Creates an MTY_App that handles input and window creation. This is the entry point for any libmatoya application, setting up the event loop infrastructure and callbacks for handling application events.

### Method
(Implicitly a creation function, typically called once)

### Endpoint
N/A (Library function)

### Parameters
- **flags** (uint32_t) - Optional - Flags for application creation.
- **app_func** (MTY_AppFunc) - Required - Callback function for the application's main loop.
- **event_func** (MTY_EventFunc) - Required - Callback function for handling application events.
- **opaque** (void*) - Optional - User-defined data passed to callback functions.

### Request Example
```c
#include "matoya.h"

typedef struct {
    bool running;
    int frame_count;
} AppState;

static bool app_func(void *opaque)
{
    AppState *state = (AppState *)opaque;
    return state->running;
}

static void event_func(const MTY_Event *evt, void *opaque)
{
    AppState *state = (AppState *)opaque;

    switch (evt->type) {
        case MTY_EVENT_CLOSE:
        case MTY_EVENT_QUIT:
            state->running = false;
            break;
        case MTY_EVENT_KEY:
            if (evt->key.key == MTY_KEY_ESCAPE && evt->key.pressed)
                state->running = false;
            break;
        default:
            break;
    }
}

int main(int argc, char **argv)
{
    AppState state = {.running = true, .frame_count = 0};
    MTY_App *app = MTY_AppCreate(0, app_func, event_func, &state);
    // ... rest of the code
    return 0;
}
```

### Response
#### Success Response (Pointer to MTY_App)
- **app** (MTY_App*) - A pointer to the created application instance.

#### Error Response (NULL)
- **MTY_GetLog()** - Returns a string describing the error.

### Response Example
```c
MTY_App *app = MTY_AppCreate(0, app_func, event_func, &state);
if (!app) {
    MTY_Log("Failed to create app: %s", MTY_GetLog());
    return 1;
}
```
```

```APIDOC
## MTY_WindowCreate

### Description
Creates an MTY_Window, the primary interactive view of an application. Windows are children of the MTY_App object and can be created, destroyed, and managed independently.

### Method
(Implicitly a creation function, typically called once)

### Endpoint
N/A (Library function)

### Parameters
- **app** (MTY_App*) - Required - Pointer to the application instance.
- **title** (const char*) - Required - The title of the window.
- **frame** (const MTY_Frame*) - Optional - Specifies the initial position and size of the window. If NULL, default values are used.
- **flags** (uint32_t) - Optional - Flags for window creation.

### Request Example
```c
#include "matoya.h"

void create_custom_window(MTY_App *app)
{
    MTY_Frame frame = {
        .x = 100,
        .y = 100,
        .w = 1280,
        .h = 720,
        .type = MTY_WINDOW_NORMAL
    };

    MTY_Window window = MTY_WindowCreate(app, "Custom Window", &frame, 0);
    if (window < 0) {
        MTY_Log("Failed to create window");
        return;
    }
    // ... other operations
}
```

### Response
#### Success Response (Window Handle)
- **window** (MTY_Window) - A handle to the created window. This is typically a non-negative integer.

#### Error Response (Negative Integer)
- **MTY_GetLog()** - Returns a string describing the error.

### Response Example
```c
MTY_Window window = MTY_WindowCreate(app, "My Application", NULL, 0);
if (window < 0) {
    MTY_Log("Failed to create window: %s", MTY_GetLog());
    MTY_AppDestroy(&app);
    return 1;
}
```
```

```APIDOC
## MTY_WindowDrawQuad

### Description
Draws a quad with a raw image and MTY_RenderDesc for GPU-accelerated rendering of video frames or images.

### Method
(Implicitly a rendering function)

### Endpoint
N/A (Library function)

### Parameters
- **app** (MTY_App*) - Required - Pointer to the application instance.
- **window** (MTY_Window) - Required - Handle to the window where the quad will be drawn.
- **image** (const void*) - Required - Pointer to the raw image data.
- **desc** (const MTY_RenderDesc*) - Required - Structure containing rendering parameters for the image.

### Request Example
```c
#include "matoya.h"

void render_frame(MTY_App *app, MTY_Window window, const void *rgba_image,
                  uint32_t width, uint32_t height)
{
    MTY_RenderDesc desc = {
        .format = MTY_COLOR_FORMAT_RGBA,
        .rotation = MTY_ROTATION_NONE,
        .filter = MTY_FILTER_LINEAR,
        .imageWidth = width,
        .imageHeight = height,
        .cropWidth = width,
        .cropHeight = height,
        .aspectRatio = (float)width / (float)height,
        .scale = 1.0f,
        .layer = 0
    };

    MTY_WindowClear(app, window, 0.0f, 0.0f, 0.0f, 1.0f);
    MTY_WindowDrawQuad(app, window, rgba_image, &desc);
    MTY_WindowPresent(app, window);
}
```

### Response
(This function typically does not return a value indicating success or failure directly, errors are usually handled via MTY_GetLog() or by the application's event loop.)

### Response Example
(No direct response body, operations are performed on the window.)
```

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

### Get App Detach State

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_AppGetDetachState

Retrieves the current detach state of the application context.

```APIDOC
## GET /api/app/detach-state

### Description
Get the app's current detach state.

### Method
GET

### Endpoint
/api/app/detach-state

### Parameters
#### Path Parameters
- **ctx** (MTY_App *) - Required - The MTY_App context.

### Response
#### Success Response (200)
- **detachState** (MTY_DetachState) - The app's current detach state.

### Response Example
```json
{
  "detachState": "Detached"
}
```
```

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

### Get Window Graphics API

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_WindowGetGFX

Retrieves the current graphics API in use by the specified window.

```APIDOC
## GET /window/graphics_api

### Description
Get the current graphics API in use by the window.

### Method
GET

### Endpoint
/window/graphics_api

### Parameters
#### Path Parameters
- **app** (MTY_App *) - Required - The MTY_App.
- **window** (MTY_Window) - Required - An MTY_Window.

### Response
#### Success Response (200)
- **MTY_GFX** (MTY_GFX) - Current graphics API in use by the window.

### Response Example
```json
{
  "graphics_api": "VULKAN" 
}
```
```

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

### Get JNI Environment

Source: https://github.com/snowcone-ltd/libmatoya/wiki/doc/MTY_GetJNIEnv

Retrieves a pointer to the thread-local JNIEnv* environment. This function is supported on Android.

```APIDOC
## MTY_GetJNIEnv

### Description
Get a pointer to the thread local `JNIEnv *` environment.

### Method
`void *`

### Endpoint
N/A (Function Call)

### Return Value
- **`void *`** - Pointer to the thread local `JNIEnv *` environment.

### Platform Support
- Android

### See Also
- [Module: System](System)
```

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

### Render an Image Quad with libmatoya

Source: https://context7.com/snowcone-ltd/libmatoya/llms.txt

This function demonstrates GPU-accelerated rendering of a raw RGBA image onto a libmatoya window. It configures rendering parameters, clears the window, draws the image, and presents the frame.

```c
#include "matoya.h"

void render_frame(MTY_App *app, MTY_Window window, const void *rgba_image,
                  uint32_t width, uint32_t height)
{
    // Configure the render description
    MTY_RenderDesc desc = {
        .format = MTY_COLOR_FORMAT_RGBA,
        .rotation = MTY_ROTATION_NONE,
        .filter = MTY_FILTER_LINEAR,
        .imageWidth = width,
        .imageHeight = height,
        .cropWidth = width,
        .cropHeight = height,
        .aspectRatio = (float)width / (float)height,
        .scale = 1.0f,
        .layer = 0
    };

    // Clear window to black
    MTY_WindowClear(app, window, 0.0f, 0.0f, 0.0f, 1.0f);

    // Draw the image quad
    MTY_WindowDrawQuad(app, window, rgba_image, &desc);

    // Present the frame
    MTY_WindowPresent(app, window);
}

```