### Install and Select Hyprcursor Theme

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Install a hyprcursor theme by extracting its archive into the icons directory and setting the HYPRCURSOR_THEME environment variable. The theme directory must contain a manifest file.

```sh
# Extract a downloaded theme archive into the icons directory
mkdir -p ~/.local/share/icons/myCursorTheme
tar -xf myCursorTheme.tar.gz -C ~/.local/share/icons/myCursorTheme

# The theme directory must contain a manifest at its root:
# ~/.local/share/icons/myCursorTheme/manifest.hl

# Select the theme by setting the environment variable
export HYPRCURSOR_THEME=myCursorTheme

# Add to your shell profile or compositor config to persist the setting
echo 'export HYPRCURSOR_THEME=myCursorTheme' >> ~/.profile
```

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

### Build Hyprcursor Library and Utilities

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Build and install libhyprcursor and hyprcursor-util using CMake. Ensure dependencies like hyprlang, cairo, libzip, librsvg, and tomlplusplus are met.

```sh
# Dependencies: hyprlang >= 0.4.2, cairo, libzip, librsvg, tomlplusplus

# Configure
cmake --no-warn-unused-cli \
  -DCMAKE_BUILD_TYPE:STRING=Release \
  -DCMAKE_INSTALL_PREFIX:PATH=/usr \
  -S . -B ./build

# Build
cmake --build ./build --config Release --target all -j$(nproc 2>/dev/null || getconf _NPROCESSORS_CONF)

# Install
sudo cmake --install build
```

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

### Install hyprcursor Theme

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Copies the compiled hyprcursor theme to the user's local icons directory for system-wide availability.

```shell
cp -r ./output/create_my_theme ~/.local/share/icons/my_theme
```

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

### Install Extracted and Compiled Theme

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Installs the compiled hyprcursor theme derived from an XCursor theme into the user's local icons directory and sets the theme environment variable.

```shell
# Install
cp -r ./compiled/create_Adwaita ~/.local/share/icons/Adwaita-hyprcursor
export HYPRCURSOR_THEME=Adwaita-hyprcursor
```

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

### Build Hyprcursor Project

Source: https://github.com/hyprwm/hyprcursor/blob/main/README.md

Use these CMake commands to configure, build, and install the hyprcursor project. Ensure dependencies like hyprlang, cairo, libzip, librsvg, and tomlplusplus are met.

```sh
cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -DCMAKE_INSTALL_PREFIX:PATH=/usr -S . -B ./build
cmake --build ./build --config Release --target all -j`nproc 2>/dev/null || getconf _NPROCESSORS_CONF`
```

```sh
sudo cmake --install build
```

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

### Get Cursor Image Data (C)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Retrieves rendered Cairo surfaces for a cursor shape and style. The returned array and its contents must be freed with `hyprcursor_cursor_image_data_free()`. Ensure to call `hyprcursor_style_done()` when the style is no longer needed.

```c
#include <hyprcursor/hyprcursor.h>
#include <cairo/cairo.h>
#include <stdio.h>

void logFn(enum eHyprcursorLogLevel level, char* msg) { printf("[hc] %s\n", msg); }

int main(void) {
    struct hyprcursor_manager_t* mgr =
        hyprcursor_manager_create_with_logger(NULL, logFn);

    if (!mgr || !hyprcursor_manager_valid(mgr)) return 1;

    struct hyprcursor_cursor_style_info info = {.size = 48};

    if (!hyprcursor_load_theme_style(mgr, info)) {
        printf("Failed to load style\n");
        hyprcursor_manager_free(mgr);
        return 1;
    }

    int dataSize = 0;
    hyprcursor_cursor_image_data** data =
        hyprcursor_get_cursor_image_data(mgr, "left_ptr", info, &dataSize);

    if (!data || dataSize == 0) {
        printf("No cursor data returned\n");
        return 1;
    }

    printf("Got %d frame(s)\n", dataSize);
    printf("Hotspot: (%d, %d)\n", data[0]->hotspotX, data[0]->hotspotY);

    // Render first frame to PNG via Cairo
    int ret = cairo_surface_write_to_png(data[0]->surface, "/tmp/arrowC.png");
    printf("Cairo write: %s\n", ret == 0 ? "OK" : "FAILED");

    // Free the image data array (surfaces remain valid until style_done)
    hyprcursor_cursor_image_data_free(data, dataSize);

    // Release style resources
    hyprcursor_style_done(mgr, info);
    hyprcursor_manager_free(mgr);
    return ret;
}
```

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

### Get Raw Cursor Shape Data (C)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Retrieves raw image bytes and metadata for a cursor shape without rendering. Check `overridenBy` to resolve aliases. Free the data immediately using `hyprcursor_raw_shape_data_free()`.

```c
#include <hyprcursor/hyprcursor.h>
#include <stdio.h>

int main(void) {
    struct hyprcursor_manager_t* mgr = hyprcursor_manager_create(NULL);
    if (!mgr || !hyprcursor_manager_valid(mgr)) return 1;

    hyprcursor_cursor_raw_shape_data* shapeData =
        hyprcursor_get_raw_shape_data(mgr, "left_ptr");

    if (!shapeData) {
        printf("Failed to get shape data\n");
        return 1;
    }

    // Resolve override aliases
    if (shapeData->overridenBy) {
        printf("left_ptr overridden by: %s\n", shapeData->overridenBy);
        hyprcursor_cursor_raw_shape_data* ov =
            hyprcursor_get_raw_shape_data(mgr, shapeData->overridenBy);
        hyprcursor_raw_shape_data_free(shapeData);
        shapeData = ov;
    }

    if (!shapeData || shapeData->len == 0) {
        printf("No images found\n");
        return 1;
    }

    printf("Images: %lu\n", shapeData->len);
    printf("Hotspot: (%.2f, %.2f)\n", shapeData->hotspotX, shapeData->hotspotY);
    printf("Type: %s\n", shapeData->type == HC_DATA_SVG ? "SVG" : "PNG");

    for (size_t i = 0; i < shapeData->len; i++) {
        printf("Frame %zu: size=%d bytes=%lu delay=%dms\n",
               i,
               shapeData->images[i].size,
               shapeData->images[i].len,
               shapeData->images[i].delay);
    }

    hyprcursor_raw_shape_data_free(shapeData);
    hyprcursor_manager_free(mgr);
    return 0;
}
```

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

### Retrieve Rendered Cursor Shape Data

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Use `getShape` to get rendered Cairo surfaces for a cursor shape. This function requires a loaded theme style and returns animated frames if available. Surfaces are valid until `cursorSurfaceStyleDone` is called.

```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <cairo/cairo.h>
#include <iostream>

void logFunction(enum eHyprcursorLogLevel level, char* msg) {
    std::cout << "[hc] " << msg << "\n";
}

int main() {
    Hyprcursor::CHyprcursorManager mgr(nullptr, logFunction);
    if (!mgr.valid()) return 1;

    Hyprcursor::SCursorStyleInfo style{.size = 48};
    if (!mgr.loadThemeStyle(style)) return 1;

    // Request the "left_ptr" (default arrow) cursor shape
    const auto SHAPEDATA = mgr.getShape("left_ptr", style);

    if (SHAPEDATA.images.empty()) {
        std::cerr << "Shape 'left_ptr' not found in theme\n";
        return 1;
    }

    std::cout << "Got " << SHAPEDATA.images.size() << " frame(s)\n";

    for (size_t i = 0; i < SHAPEDATA.images.size(); ++i) {
        const auto& img = SHAPEDATA.images[i];
        std::cout << "Frame " << i
                  << ": size=" << img.size
                  << " delay=" << img.delay << "ms"
                  << " hotspot=(" << img.hotspotX << "," << img.hotspotY << ")\n";
    }

    // Write first frame to PNG using Cairo
    int ret = cairo_surface_write_to_png(SHAPEDATA.images[0].surface, "/tmp/arrow.png");
    std::cout << "Cairo write result: " << ret << "\n"; // 0 = success

    // Release resources for this style
    mgr.cursorSurfaceStyleDone(style);
    return ret;
}
// Output:
// [hc] Loaded theme: Bibata-Modern-Ice
// Got 1 frame(s)
// Frame 0: size=48 delay=200ms hotspot=(0,0)
// Cairo write result: 0

```

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

### Create Hyprcursor Theme (Shell)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Use the `hyprcursor-util` command-line tool to compile a directory of cursor assets into a `.hlc` theme file.

```sh
hyprcursor-util --create
```

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

### TOML Cursor Meta-data Configuration

Source: https://github.com/hyprwm/hyprcursor/blob/main/docs/MAKING_THEMES.md

Demonstrates configuring cursor meta-data in TOML, including merging multiple 'define' keys into single semicolon-separated strings.

```toml
[General]
resize_algorithm = "bilinear"
hotspot_x = "0.0"
hotspot_y = "0.0"
define_override = 'shape1;shape2;shape3'
define_size = '24,image1.png,200;24,image2.png,200;32,image3.png,200'
```

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

### TOML Manifest Configuration for Hyprcursor Themes

Source: https://github.com/hyprwm/hyprcursor/blob/main/docs/MAKING_THEMES.md

Shows how to configure the theme manifest using TOML format, requiring a [General] section and quoted values.

```toml
[General]
name = "My theme!"
description = "Very cool!"
version = "0.1"
cursors_directory = "hyprcursors"
```

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

### Create Hyprcursor Manager with Logger (C)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Initializes a cursor manager with an optional logging function. Pass NULL for the theme name to auto-detect. Always validate the manager using `hyprcursor_manager_valid()` and free it with `hyprcursor_manager_free()` when done.

```c
#include <hyprcursor/hyprcursor.h>
#include <stdio.h>

void logFunction(enum eHyprcursorLogLevel level, char* message) {
    printf("[hc] %s\n", message);
}

int main(void) {
    // Create with logger (recommended, since 0.1.6)
    struct hyprcursor_manager_t* mgr =
        hyprcursor_manager_create_with_logger(NULL, logFunction);

    if (!mgr) {
        fprintf(stderr, "Failed to allocate manager\n");
        return 1;
    }

    if (!hyprcursor_manager_valid(mgr)) {
        fprintf(stderr, "Manager invalid: no theme found\n");
        hyprcursor_manager_free(mgr);
        return 1;
    }

    printf("Theme loaded successfully\n");
    hyprcursor_manager_free(mgr);
    return 0;
}
```

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

### Create hyprcursor Theme Manifest (.hl)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Defines the general properties of a hyprcursor theme. This file is required for any theme.

```shell
cat > my_theme/manifest.hl << 'EOF'
name = My Theme
description = A custom hyprcursor theme
version = 0.1
cursors_directory = hyprcursors
EOF
```

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

### Define Animated Cursor Metadata (.hl)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Configures an animated cursor by specifying multiple frames with associated delays in milliseconds. Each frame is defined using `define_size`.

```shell
cat > my_theme/hyprcursors/wait/meta.hl << 'EOF'
resize_algorithm = bilinear
hotspot_x = 0.5
hotspot_y = 0.5
define_size = 32, frame1.png, 100
define_size = 32, frame2.png, 100
define_size = 32, frame3.png, 100
EOF
```

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

### Initialize CHyprcursorManager in C++

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Initialize CHyprcursorManager to load a cursor theme. Pass nullptr to auto-detect from the HYPRCURSOR_THEME environment variable, or a theme name string. An optional logger function can be provided.

```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

// Logger callback: msg is caller-owned and will be freed after the call
void logFunction(enum eHyprcursorLogLevel level, char* message) {
    std::cout << "[hc] " << message << "\n";
}

int main() {
    // Load default theme from environment, with logging
    Hyprcursor::CHyprcursorManager mgr(nullptr, logFunction);

    // Load a specific named theme (no logger)
    // Hyprcursor::CHyprcursorManager mgr("Bibata-Modern-Ice");

    // Always check validity before use
    if (!mgr.valid()) {
        std::cerr << "Failed to load cursor theme\n";
        return 1;
    }

    std::cout << "Theme loaded successfully\n";
    return 0;
}
```

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

### Create hyprcursor Theme Manifest (.toml)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Defines the general properties of a hyprcursor theme using TOML format. This is an alternative to the hyprlang `.hl` format.

```toml
# manifest.toml  (rename from manifest.hl)
[General]
name = "My Theme"
description = "A custom hyprcursor theme"
version = "0.1"
cursors_directory = "hyprcursors"
```

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

### Directory Structure for a Hyprcursor Theme

Source: https://github.com/hyprwm/hyprcursor/blob/main/docs/MAKING_THEMES.md

Illustrates the expected file and directory layout for a custom hyprcursor theme.

```ini
directory
 ┣ manifest.hl
 ┗ hyprcursors
   ┣ left_ptr
     ┣ image32.png
     ┣ image64.png
     ┗ meta.hl
   ┣ hand
     ┣ image32.png
     ┣ image64.png
     ┗ meta.hl
   ...
```

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

### loadThemeStyle()

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Loads and renders cursor images for a specified pixel size. This must be called before `getShape()`. After use, `cursorSurfaceStyleDone()` should be called to free associated memory.

```APIDOC
## loadThemeStyle()

### Description
Loads and renders cursor images for a given pixel size, synchronously. Must be called before `getShape()`. The `SCursorStyleInfo` struct specifies the desired cursor size in pixels; a size of `0` means unspecified/any. Call `cursorSurfaceStyleDone()` when this size is no longer needed to free the associated memory.

### Method
```cpp
bool loadThemeStyle(SCursorStyleInfo& style) noexcept
```

### Parameters
#### Request Body
- **style** (SCursorStyleInfo&) - A struct containing style information, including the desired `size` in pixels.

### Request Example
```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

int main() {
    Hyprcursor::CHyprcursorManager mgr(nullptr);
    if (!mgr.valid()) return 1;

    // Request cursors rendered at 48x48 pixels
    Hyprcursor::SCursorStyleInfo style{.size = 48};

    if (!mgr.loadThemeStyle(style)) {
        std::cerr << "Failed to load style at size 48\n";
        return 1;
    }

    std::cout << "Style loaded. Cursors are now rendered at 48px.\n";

    // ... use getShape() here ...

    // Release style resources when done (e.g., user changed cursor size)
    mgr.cursorSurfaceStyleDone(style);
    return 0;
}
```
```

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

### Cursor Meta-data Configuration

Source: https://github.com/hyprwm/hyprcursor/blob/main/docs/MAKING_THEMES.md

Specifies how a cursor should be rendered, including resizing algorithms, hotspot coordinates, cursor name overrides, and size variants. Supports PNG and SVG image types.

```hyprlang
# what resize algorithm to use when a size is requested
# that doesn't match any of your predefined ones.
# available: bilinear, nearest, none. None will pick the closest. Nearest is nearest neighbor.
resize_algorithm = bilinear

# "hotspot" is where in your cursor the actual "click point" should be.
# this is in absolute coordinates. x+ is east, y+ is south.
# the pixel coordinates of the hotspot at size are rounded to the nearest:
# (round(size * hotspot_x), round(size * hotspot_y))
hotspot_x = 0.0 # this goes 0 - 1
hotspot_y = 0.0 # this goes 0 - 1

# Define what cursor images this one should override.
# What this means is that a request for a cursor name e.g. "arrow"
# will instead use this one, even if this one is named something else.
# There is no unified list for all the available cursor names but this wayland list could be used as a reference https://gitlab.freedesktop.org/wayland/wayland-protocols/-/blob/main/staging/cursor-shape/cursor-shape-v1.xml#L71 for wayland specific cursors.
define_override = arrow
define_override = default

# define your size variants.
# Multiple size variants for the same size are treated as an animation.
define_size = 64, image64.png
define_size = 32, image32.png

# If you want to animate it, add a timeout in ms at the end:
# define_size = 64, anim1.png, 500
# define_size = 64, anim2.png, 500
# define_size = 64, anim3.png, 500
# define_size = 64, anim4.png, 500
# Make sure the timeout is > 0, as otherwise the consumer might ignore your timeouts for being invalid.
```

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

### CHyprcursorManager Constructor

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Initializes the CHyprcursorManager. It can load a specific theme by name, or auto-detect the theme from the HYPRCURSOR_THEME environment variable. An optional logger function can be provided for diagnostic output.

```APIDOC
## CHyprcursorManager Constructor

### Description
Initializes the `CHyprcursorManager`. It can load a specific theme by name, or auto-detect the theme from the `HYPRCURSOR_THEME` environment variable. An optional logger function can be provided for diagnostic output.

### Method
```cpp
Hyprcursor::CHyprcursorManager(const char* themeName, void (*logger)(enum eHyprcursorLogLevel, char*)) noexcept
```

### Parameters
#### Path Parameters
- **themeName** (const char*) - Optional - The name of the cursor theme to load. If `nullptr`, the theme is auto-detected from the `HYPRCURSOR_THEME` environment variable, falling back to the first theme found.
- **logger** (void (*)(enum eHyprcursorLogLevel, char*)) - Optional - A callback function for logging diagnostic messages. The message string is caller-owned and will be freed after the call.

### Request Example
```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

void logFunction(enum eHyprcursorLogLevel level, char* message) {
    std::cout << "[hc] " << message << "\n";
}

int main() {
    // Load default theme from environment, with logging
    Hyprcursor::CHyprcursorManager mgr(nullptr, logFunction);

    // Load a specific named theme (no logger)
    // Hyprcursor::CHyprcursorManager mgr("Bibata-Modern-Ice");

    if (!mgr.valid()) {
        std::cerr << "Failed to load cursor theme\n";
        return 1;
    }

    std::cout << "Theme loaded successfully\n";
    return 0;
}
```
```

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

### Define Cursor Shape Metadata (.hl)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Configures a specific cursor shape, including resize algorithm, hotspot, and image definitions for different sizes. Supports aliasing with `define_override`.

```shell
cat > my_theme/hyprcursors/left_ptr/meta.hl << 'EOF'
resize_algorithm = bilinear
hotspot_x = 0.0
hotspot_y = 0.0
define_override = arrow
define_override = default
define_size = 32, image32.png
define_size = 64, image64.png
EOF
```

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

### Define Cursor Shape Metadata (.toml)

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Configures a specific cursor shape using TOML, including resize algorithm, hotspot, and image definitions. Supports multiple overrides and sizes/frames.

```toml
# meta.toml  (rename from meta.hl, inside a cursor shape directory)
[General]
resize_algorithm = "bilinear"
hotspot_x = 0.0
hotspot_y = 0.0

# Multiple overrides: semicolon-separated in a single key
define_override = "arrow;default;left_ptr"

# Multiple sizes + animation frames: semicolon-separated entries
# Format: "size,image[,delay_ms]"
define_size = "32,image32.png;64,image64.png"

# Animated cursor example (all frames same size, different images):
# define_size = "32,frame1.png,100;32,frame2.png,100;32,frame3.png,100"
```

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

### Extract XCursor Theme to Working State

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Converts an existing XCursor theme into a hyprcursor working state, which can then be edited and recompiled. Requires `xcur2png` at runtime.

```shell
# Extract an XCursor theme into a working state (requires xcur2png at runtime)
hyprcursor-util --extract /usr/share/icons/Adwaita -o ./working/
# Creates: ./working/extract_Adwaita/
```

```shell
# (Optional) Override the default resize algorithm during extraction
hyprcursor-util --extract /usr/share/icons/Adwaita --resize bilinear -o ./working/
```

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

### Load Cursor Style with CHyprcursorManager in C++

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Load and render cursor images for a specific pixel size using loadThemeStyle(). This must be called before getShape(). Release resources with cursorSurfaceStyleDone() when the style is no longer needed.

```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

int main() {
    Hyprcursor::CHyprcursorManager mgr(nullptr);
    if (!mgr.valid()) return 1;

    // Request cursors rendered at 48x48 pixels
    Hyprcursor::SCursorStyleInfo style{.size = 48};

    if (!mgr.loadThemeStyle(style)) {
        std::cerr << "Failed to load style at size 48\n";
        return 1;
    }

    std::cout << "Style loaded. Cursors are now rendered at 48px.\n";

    // ... use getShape() here ...

    // Release style resources when done (e.g., user changed cursor size)
    mgr.cursorSurfaceStyleDone(style);
    return 0;
}
```

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

### Edit Extracted Theme Files

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Allows for manual editing of the `manifest.hl` and `meta.hl` files after a theme has been extracted, enabling customization.

```shell
# Review and edit the generated manifest.hl and meta.hl files as needed
nano ./working/extract_Adwaita/manifest.hl
nano ./working/extract_Adwaita/hyprcursors/left_ptr/meta.hl
```

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

### Compile hyprcursor Theme

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Compiles a hyprcursor theme from a working directory into a distributable format. The `-o` flag specifies the output parent directory.

```shell
hyprcursor-util --create my_theme -o ./output/
# Creates: ./output/create_my_theme/
```

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

### hyprcursor_manager_create / hyprcursor_manager_create_with_logger

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Creates a cursor manager instance. The `hyprcursor_manager_create_with_logger` variant allows for custom logging. The manager must be freed using `hyprcursor_manager_free`.

```APIDOC
## C API — `hyprcursor_manager_create` / `hyprcursor_manager_create_with_logger`

Creates a cursor manager from C. Returns an opaque `hyprcursor_manager_t*` pointer owned by the caller; must be freed with `hyprcursor_manager_free()`.
Pass `NULL` as the theme name to auto-detect. Always verify the result with `hyprcursor_manager_valid()`.
Available with logger variant since v0.1.6.
```

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

### Hyprcursor Theme Manifest Configuration

Source: https://github.com/hyprwm/hyprcursor/blob/main/docs/MAKING_THEMES.md

Defines the metadata for a hyprcursor theme, including its name, description, version, and the directory where cursor assets are located.

```hyprlang
name = My theme!
description = Very cool!
version = 0.1
cursors_directory = hyprcursors # has to match the directory in the structure
```

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

### hyprcursor_get_cursor_image_data / hyprcursor_cursor_image_data_free

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Retrieves an array of rendered Cairo surfaces for a specified cursor shape and style. The returned array and its contents must be freed using `hyprcursor_cursor_image_data_free()`.

```APIDOC
## C API — `hyprcursor_get_cursor_image_data` / `hyprcursor_cursor_image_data_free`

Returns an array of `hyprcursor_cursor_image_data*` (rendered Cairo surfaces) for a given shape name and style. The `out_size` parameter is populated with the array length. The entire pointer array must be freed immediately after use with `hyprcursor_cursor_image_data_free()`.
Call `hyprcursor_style_done()` when the style is no longer needed.
```

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

### Compile Extracted Working State

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Compiles the extracted and potentially modified working state of an XCursor theme into a distributable hyprcursor theme archive.

```shell
# Compile the working state into a distributable hyprcursor theme
hyprcursor-util --create ./working/extract_Adwaita -o ./compiled/
# Creates: ./compiled/create_Adwaita/
```

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

### Check CHyprcursorManager Validity in C++

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Check if the CHyprcursorManager was initialized successfully using the valid() method. This should be done before using any other manager methods to ensure the theme loaded correctly.

```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

int main() {
    Hyprcursor::CHyprcursorManager mgr("NonExistentTheme");

    if (!mgr.valid()) {
        // Safe to handle gracefully — fall back to XCursor or exit
        std::cerr << "Cursor theme not found or invalid, falling back.\n";
        return 1;
    }

    // Proceed safely knowing the theme is loaded
    std::cout << "Theme is valid and ready.\n";
    return 0;
}
```

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

### CHyprcursorManager::valid()

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Checks if the cursor theme was loaded successfully. This method should be called after initializing `CHyprcursorManager` to ensure the theme is valid before proceeding.

```APIDOC
## CHyprcursorManager::valid()

### Description
Returns `true` if the theme was loaded successfully. A manager is invalid if no themes are found, the specified theme name doesn't exist, the theme fails to parse, or it contains no valid cursor shapes. Always check this before calling any other methods.

### Method
```cpp
bool valid() const noexcept
```

### Response Example
```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

int main() {
    Hyprcursor::CHyprcursorManager mgr("NonExistentTheme");

    if (!mgr.valid()) {
        // Safe to handle gracefully — fall back to XCursor or exit
        std::cerr << "Cursor theme not found or invalid, falling back.\n";
        return 1;
    }

    // Proceed safely knowing the theme is loaded
    std::cout << "Theme is valid and ready.\n";
    return 0;
}
```
```

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

### getRawShapeData()

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Returns the raw, un-rendered image bytes of a cursor shape alongside its metadata, without loading any style. Intended for compositors or DEs that implement their own renderer. Returns a SCursorRawShapeData with the raw PNG or SVG bytes, hotspot fractions (0.0–1.0), resize algorithm, data type, and an overridenBy field that must be checked to resolve cursor name aliases.

```APIDOC
## C++ API — `getRawShapeData()`

### Description
Returns the raw, un-rendered image bytes of a cursor shape alongside its metadata, without loading any style. Intended for compositors or DEs that implement their own renderer. Returns a `SCursorRawShapeData` with the raw PNG or SVG bytes, hotspot fractions (0.0–1.0), resize algorithm, data type, and an `overridenBy` field that must be checked to resolve cursor name aliases.

### Usage Example
```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>
#include <fstream>

int main() {
    Hyprcursor::CHyprcursorManager mgr(nullptr);
    if (!mgr.valid()) return 1;

    // No loadThemeStyle() needed for raw data
    auto RAWDATA = mgr.getRawShapeData("left_ptr");

    // Resolve overrides (cursor name aliases)
    if (RAWDATA.images.empty() && !RAWDATA.overridenBy.empty()) {
        std::cout << "left_ptr is overridden by: " << RAWDATA.overridenBy << "\n";
        RAWDATA = mgr.getRawShapeData(RAWDATA.overridenBy.c_str());
    }

    if (RAWDATA.images.empty()) {
        std::cerr << "No images found for left_ptr\n";
        return 1;
    }

    std::cout << "Data type: " << (RAWDATA.type == HC_DATA_SVG ? "SVG" : "PNG") << "\n";
    std::cout << "Hotspot: (" << RAWDATA.hotspotX << ", " << RAWDATA.hotspotY << ")\n";
    std::cout << "Frames: " << RAWDATA.images.size() << "\n";

    // Write the raw bytes of the first frame to disk
    const auto& frame0 = RAWDATA.images[0];
    std::cout << "Frame 0: nominal_size=" << frame0.size
              << " delay=" << frame0.delay << "ms"
              << " data_bytes=" << frame0.data.size() << "\n";

    std::ofstream out("/tmp/left_ptr_raw.png", std::ios::binary);
    out.write(reinterpret_cast<const char*>(frame0.data.data()), frame0.data.size());

    return 0;
}
```
```

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

### getShape()

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Retrieves the rendered Cairo surface(s) for a named cursor shape at a previously loaded style. Returns a SCursorShapeData containing a vector of SCursorImageData frames, each with a cairo_surface_t*, pixel size, animation delay (ms), and hotspot coordinates. Multiple images indicate an animated cursor. The surfaces remain valid until cursorSurfaceStyleDone() is called on the owning style.

```APIDOC
## C++ API — `getShape()`

### Description
Retrieves the rendered Cairo surface(s) for a named cursor shape at a previously loaded style. Returns a `SCursorShapeData` containing a vector of `SCursorImageData` frames, each with a `cairo_surface_t*`, pixel size, animation delay (ms), and hotspot coordinates. Multiple images indicate an animated cursor. The surfaces remain valid until `cursorSurfaceStyleDone()` is called on the owning style.

### Usage Example
```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <cairo/cairo.h>
#include <iostream>

void logFunction(enum eHyprcursorLogLevel level, char* msg) {
    std::cout << "[hc] " << msg << "\n";
}

int main() {
    Hyprcursor::CHyprcursorManager mgr(nullptr, logFunction);
    if (!mgr.valid()) return 1;

    Hyprcursor::SCursorStyleInfo style{.size = 48};
    if (!mgr.loadThemeStyle(style)) return 1;

    // Request the "left_ptr" (default arrow) cursor shape
    const auto SHAPEDATA = mgr.getShape("left_ptr", style);

    if (SHAPEDATA.images.empty()) {
        std::cerr << "Shape 'left_ptr' not found in theme\n";
        return 1;
    }

    std::cout << "Got " << SHAPEDATA.images.size() << " frame(s)\n";

    for (size_t i = 0; i < SHAPEDATA.images.size(); ++i) {
        const auto& img = SHAPEDATA.images[i];
        std::cout << "Frame " << i
                  << ": size=" << img.size
                  << " delay=" << img.delay << "ms"
                  << " hotspot=(" << img.hotspotX << "," << img.hotspotY << ")\n";
    }

    // Write first frame to PNG using Cairo
    int ret = cairo_surface_write_to_png(SHAPEDATA.images[0].surface, "/tmp/arrow.png");
    std::cout << "Cairo write result: " << ret << "\n"; // 0 = success

    // Release resources for this style
    mgr.cursorSurfaceStyleDone(style);
    return ret;
}
```
```

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

### Register Custom Logging Callback

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Use `registerLoggingFunction` to set a custom callback for Hyprcursor logs. Pass `nullptr` to unregister. This function is available since v0.1.6 and allows for custom log handling.

```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

void verboseLogger(enum eHyprcursorLogLevel level, char* msg) {
    const char* levelStr[] = {"NONE", "TRACE", "INFO", "WARN", "ERR", "CRITICAL"};
    std::cout << "[" << levelStr[level] << "] " << msg << "\n";
}

int main() {
    // Create manager without logger initially
    Hyprcursor::CHyprcursorManager mgr(nullptr);

    // Register logger after construction
    mgr.registerLoggingFunction(verboseLogger);

    if (!mgr.valid()) return 1;

    Hyprcursor::SCursorStyleInfo style{.size = 32};
    mgr.loadThemeStyle(style);

    // Unregister logger when no longer needed
    mgr.registerLoggingFunction(nullptr);

    mgr.cursorSurfaceStyleDone(style);
    return 0;
}

```

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

### hyprcursor_get_raw_shape_data / hyprcursor_raw_shape_data_free

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Fetches raw image bytes and metadata for a cursor shape without rendering. This function is useful for accessing underlying data and resolving overrides. The returned data must be freed with `hyprcursor_raw_shape_data_free()`.

```APIDOC
## C API — `hyprcursor_get_raw_shape_data` / `hyprcursor_raw_shape_data_free`

Returns a `hyprcursor_cursor_raw_shape_data*` containing raw image bytes and cursor metadata without rendering. Check `overridenBy` to resolve cursor aliases before accessing images. Free immediately after use with `hyprcursor_raw_shape_data_free()`.
Available since v0.1.6.
```

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

### registerLoggingFunction()

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Registers or unregisters a logging callback on an existing manager instance. The callback receives a log level (HC_LOG_TRACE, HC_LOG_INFO, HC_LOG_WARN, HC_LOG_ERR, HC_LOG_CRITICAL) and a message string owned by the caller. Pass nullptr to remove a previously registered logger. Available since v0.1.6.

```APIDOC
## C++ API — `registerLoggingFunction()`

### Description
Registers or unregisters a logging callback on an existing manager instance. The callback receives a log level (`HC_LOG_TRACE`, `HC_LOG_INFO`, `HC_LOG_WARN`, `HC_LOG_ERR`, `HC_LOG_CRITICAL`) and a message string owned by the caller. Pass `nullptr` to remove a previously registered logger. Available since v0.1.6.

### Usage Example
```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>

void verboseLogger(enum eHyprcursorLogLevel level, char* msg) {
    const char* levelStr[] = {"NONE", "TRACE", "INFO", "WARN", "ERR", "CRITICAL"};
    std::cout << "[" << levelStr[level] << "] " << msg << "\n";
}

int main() {
    // Create manager without logger initially
    Hyprcursor::CHyprcursorManager mgr(nullptr);

    // Register logger after construction
    mgr.registerLoggingFunction(verboseLogger);

    if (!mgr.valid()) return 1;

    Hyprcursor::SCursorStyleInfo style{.size = 32};
    mgr.loadThemeStyle(style);

    // Unregister logger when no longer needed
    mgr.registerLoggingFunction(nullptr);

    mgr.cursorSurfaceStyleDone(style);
    return 0;
}
```
```

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

### Retrieve Raw Cursor Shape Data

Source: https://context7.com/hyprwm/hyprcursor/llms.txt

Use `getRawShapeData` to obtain the raw image bytes (PNG or SVG) of a cursor shape without loading a style. This is useful for custom renderers. It returns hotspot fractions and handles cursor name overrides.

```cpp
#include <hyprcursor/hyprcursor.hpp>
#include <iostream>
#include <fstream>

int main() {
    Hyprcursor::CHyprcursorManager mgr(nullptr);
    if (!mgr.valid()) return 1;

    // No loadThemeStyle() needed for raw data
    auto RAWDATA = mgr.getRawShapeData("left_ptr");

    // Resolve overrides (cursor name aliases)
    if (RAWDATA.images.empty() && !RAWDATA.overridenBy.empty()) {
        std::cout << "left_ptr is overridden by: " << RAWDATA.overridenBy << "\n";
        RAWDATA = mgr.getRawShapeData(RAWDATA.overridenBy.c_str());
    }

    if (RAWDATA.images.empty()) {
        std::cerr << "No images found for left_ptr\n";
        return 1;
    }

    std::cout << "Data type: " << (RAWDATA.type == HC_DATA_SVG ? "SVG" : "PNG") << "\n";
    std::cout << "Hotspot: (" << RAWDATA.hotspotX << ", " << RAWDATA.hotspotY << ")\n";
    std::cout << "Frames: " << RAWDATA.images.size() << "\n";

    // Write the raw bytes of the first frame to disk
    const auto& frame0 = RAWDATA.images[0];
    std::cout << "Frame 0: nominal_size=" << frame0.size
              << " delay=" << frame0.delay << "ms"
              << " data_bytes=" << frame0.data.size() << "\n";

    std::ofstream out("/tmp/left_ptr_raw.png", std::ios::binary);
    out.write(reinterpret_cast<const char*>(frame0.data.data()), frame0.data.size());

    return 0;
}
// Output:
// Data type: PNG
// Hotspot: (0, 0)
// Frames: 1
// Frame 0: nominal_size=32 delay=200ms data_bytes=1452

```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.