### Configuration Lookup Example

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

Illustrates how to find information about command-line options and their behavior in the documentation.

```text
Looking for: --scale option behavior
1. Open quick-reference.md → Command-Line Interface
2. See option summary with types
3. Open configuration.md → Zoom & Display Options
4. Find detailed explanation with examples
```

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

### Logging Examples

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-utilities.md

Demonstrates various ways to use the Debug::log function with different log levels and format strings. Includes examples for general messages, warnings, errors, critical failures, verbose tracing, and raw output.

```cpp
#include "src/debug/Log.hpp"

Debug::log(LOG, "Hyprpicker initialized");
Debug::log(WARN, "Optional feature not available: %s", "cursor_shape_v1");
Debug::log(ERR, "Buffer format not supported: %u", format);
Debug::log(CRIT, "Wayland connection failed!");
Debug::log(TRACE, "Frame ready: pixel %.0fx%.0f", width, height);
Debug::log(NONE, "#FF5733");  // Color output, no prefix
```

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

### Architecture Lookup Example

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

Shows the steps to understand the project's architecture, specifically the rendering process.

```text
Understanding: How rendering works
1. Open overview.md → Data Flow
2. Read rendering sequence
3. Open module-structure.md → Rendering Sequence
4. See detailed callback flow
5. Refer to api-reference-CLayerSurface.md for details
```

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

### Build hyprpicker with CMake

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

Use these CMake commands to configure, build, and install hyprpicker from source. Ensure all dependencies are installed first.

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

```bash
cmake --install ./build
```

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

### API Lookup Example

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

Demonstrates the process of looking up API details for a specific function within the documentation.

```text
Looking for: CHyprpicker::outputColor()
1. Open quick-reference.md
2. Find CHyprpicker class section
3. Get signature
4. Open api-reference-CHyprpicker.md
5. Find detailed documentation with examples
```

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

### Example: Setting up and initializing SMonitor Screencopy Frame

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SMonitor.md

Demonstrates how to obtain a monitor instance, create a screencopy frame, and initialize it using initSCFrame(). Ensure the screencopy manager is set up to send capture output.

```cpp
SMonitor* mon = g_pHyprpicker->m_vMonitors[0].get();
mon->pSCFrame = makeShared<CCZwlrScreencopyFrameV1>(
    g_pHyprpicker->m_pScreencopyMgr->sendCaptureOutput(false, mon->output->resource())
);
mon->initSCFrame();
```

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

### CHyprpicker::init()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Initializes the Wayland connection, binds to necessary interfaces, and starts the main event loop. Exits with code 1 if Wayland or screencopy protocol is unavailable.

```APIDOC
## CHyprpicker::init()

### Description
Initializes the Wayland connection, binds to all required Wayland interfaces, and starts the main event loop.

### Behavior
1. Creates XKB context for keyboard support
2. Connects to Wayland compositor
3. Registers global interface listener for binding to compositor, shm, layer shell, seat, outputs, and screencopy
4. Creates layer surfaces for each connected monitor
5. Initiates screencopy frames for all outputs
6. Enters blocking event dispatch loop until application termination

### Returns
`void`

### Throws
Exits with code 1 if:
- No Wayland compositor is running
- zwlr_screencopy_v1 protocol is not available

### Example
```cpp
g_pHyprpicker = std::make_unique<CHyprpicker>();
g_pHyprpicker->init();
```
```

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

### Initialize CHyprpicker

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Initializes the Wayland connection, binds to necessary interfaces, and starts the event loop. Exits if no Wayland compositor is running or screencopy protocol is unavailable.

```cpp
void init();
```

```cpp
g_pHyprpicker = std::make_unique<CHyprpicker>();
g_pHyprpicker->init();
```

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

### Initialize Monitor Setup in Hyprpicker

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SMonitor.md

This C++ code snippet, intended for `CHyprpicker::init()`, iterates through registered monitors to set up layer surfaces and initiate screencopy capture for each. Ensure `m_pScreencopyMgr` is initialized before use. Each screencopy frame is single-use.

```cpp
// In CHyprpicker::init()
for (auto& monitor : m_vMonitors) {
    // Create layer surface for overlay
    m_vLayerSurfaces.emplace_back(std::make_unique<CLayerSurface>(monitor.get()));
    
    // Link layer surface to monitor
    monitor->pLS = m_vLayerSurfaces.back().get();
    
    // Start screencopy capture
    monitor->pSCFrame = makeShared<CCZwlrScreencopyFrameV1>(
        m_pScreencopyMgr->sendCaptureOutput(m_bIncludeCursor, monitor->output->resource())
    );
    
    // Set up screencopy listeners
    monitor->initSCFrame();
}
```

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

### Common Vector2D Usage Examples

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Illustrates common ways to initialize and use the Vector2D type for dimensions, coordinates, and scaling operations.

```cpp
Vector2D size{1920, 1080};         // Width, height in pixels
Vector2D coords = m_vLastCoords;   // Mouse position
Vector2D scale = size * factor;    // Scaling operation
```

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

### Set Active Output Mode (eOutputMode Usage)

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Example of how to set the active output mode for Hyprpicker. Ensure the selected mode is valid.

```cpp
g_pHyprpicker->m_bSelectedOutputMode = OUTPUT_RGB;
```

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

### Apply Wayland Output Transform

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Example of setting a monitor transform and checking for rotation to adjust buffer dimensions accordingly. Requires the `wl_output_transform` enum.

```cpp
SMonitor::transform = WL_OUTPUT_TRANSFORM_90;  // Monitor is rotated 90°

// Check if transform includes rotation (not just flip)
if (transform % 2 == 1) {  // 90° or 270°
    std::swap(buffer->pixelSize.x, buffer->pixelSize.y);  // Swap dimensions
}
```

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

### Get Component Count for Output Mode (numOutputValues Usage)

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Example of retrieving the number of color components for the currently selected output mode using the `numOutputValues` array.

```cpp
uint8_t componentCount = numOutputValues[g_pHyprpicker->m_bSelectedOutputMode];
```

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

### Wayland Callback Example: Layer Surface Configuration

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/module-structure.md

This snippet illustrates setting up a callback for layer surface configuration events. It's used to acknowledge configuration changes.

```cpp
pLayerSurface->setConfigure([this](CCZwlrLayerSurfaceV1* r, ...) { /* ack */ });
```

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

### Get HEX Color Output

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CColor.md

Demonstrates how to get a CColor object and format its RGB components into a HEX string. Assumes getColorFromPixel is available.

```cpp
CColor color = getColorFromPixel(surface, position);
std::string hex = std::format("#{0:02x}{1:02x}{2:02x}", color.r, color.g, color.b);
// Example: #ff5733
```

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

### Hyprpicker Trace Logging Examples

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/errors.md

These messages are emitted when the --verbose or -v flag is used, aiding in the diagnosis of rendering and buffer problems.

```log
[TRACE] Frame ready: pixel 1920x1080, xfmd: 1920x1080
```

```log
[TRACE] renderSurface: scalebufs 1.00x1.00
```

```log
[TRACE] Received a preferredScale for HDMI-1: 1.25
```

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

### Shared Pointer Usage Examples

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Demonstrates the usage of the 'SP' macro alias for declaring shared pointers to various Wayland protocol wrapper classes.

```cpp
SP<CCWlCompositor> compositor;       // Equivalent to CSharedPointer<CCWlCompositor>
SP<CCZwlrLayerSurfaceV1> surface;
SP<SPoolBuffer> buffer;
```

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

### NClipboard::copy()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-utilities.md

Asynchronously copies the provided string to the Wayland clipboard using the `wl-copy` command. This function is non-blocking and requires the `wl-clipboard` package to be installed.

```APIDOC
## NClipboard::copy()

### Description
Copies the provided string data to the system clipboard asynchronously.

### Method
void

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **data** (std::string) - Required - Text content to copy to the clipboard

### Request Example
```cpp
#include "src/clipboard/Clipboard.hpp"

std::string hexColor = "#FF5733";
NClipboard::copy(hexColor);  // Non-blocking, returns immediately
```

### Response
#### Success Response (void)
This function returns void.

#### Response Example
None
```

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

### initSCFrame()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SMonitor.md

Sets up listeners for the screencopy frame to receive screen capture data. This method is called immediately after CHyprpicker::init() creates a screencopy frame for a monitor. It handles buffer setup, flag updates, frame completion, and failure scenarios, including automatic transformation handling for rotated displays.

```APIDOC
## initSCFrame()

### Description
Sets up listeners for the screencopy frame to receive screen capture data. Called immediately after `CHyprpicker::init()` creates a screencopy frame for this monitor.

### Method
`void initSCFrame()`

### Parameters
None

### Behavior:
1. **setBuffer callback:** Receives frame dimensions and format, stores them, creates the screen buffer if needed, and submits it for pixel data.
2. **setFlags callback:** Receives screencopy flags, stores them, and calls `CHyprpicker::recheckACK()`.
3. **setReady callback:** Handles pixel format conversion, rotation transformation, Cairo transformations, calls `CHyprpicker::renderSurface()`, and resets the screencopy frame.
4. **setFailed callback:** Logs a critical error and exits the application if screencopy fails.

### Transform Handling:
When the `transform` member is non-zero, `initSCFrame()` automatically swaps X and Y dimensions, applies Cairo matrix transformations for rotation, and adjusts translation based on the rotation angle.

### Example:
```cpp
SMonitor* mon = g_pHyprpicker->m_vMonitors[0].get();
mon->pSCFrame = makeShared<CCZwlrScreencopyFrameV1>(
    g_pHyprpicker->m_pScreencopyMgr->sendCaptureOutput(false, mon->output->resource())
);
mon->initSCFrame();
```

### Transform Enum:
```cpp
enum wl_output_transform {
    WL_OUTPUT_TRANSFORM_NORMAL = 0,
    WL_OUTPUT_TRANSFORM_90 = 1,
    WL_OUTPUT_TRANSFORM_180 = 2,
    WL_OUTPUT_TRANSFORM_270 = 3,
    WL_OUTPUT_TRANSFORM_FLIPPED = 4,
    WL_OUTPUT_TRANSFORM_FLIPPED_90 = 5,
    WL_OUTPUT_TRANSFORM_FLIPPED_180 = 6,
    WL_OUTPUT_TRANSFORM_FLIPPED_270 = 7,
};
```
```

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

### Wayland Callback Example: Screencopy Frame Ready

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/module-structure.md

This snippet shows how to register a callback for when a screencopy frame is ready. The callback is designed to trigger rendering operations.

```cpp
pSCFrame->setReady([this](CCZwlrScreencopyFrameV1* r, ...) { /* render */ });
```

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

### Get RGB Color Output

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CColor.md

Shows how to retrieve a CColor object and format its RGB components into a space-separated string. Assumes getColorFromPixel is available.

```cpp
CColor color = getColorFromPixel(surface, position);
std::string rgb = std::format("{} {} {}", color.r, color.g, color.b);
// Example: 255 87 51
```

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

### Copy text to clipboard

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-utilities.md

Asynchronously copies the provided string to the Wayland clipboard using the `wl-copy` command. Requires `wl-clipboard` package to be installed. This function spawns a separate process and does not wait for completion. If `wl-copy` is not available, the operation fails silently.

```cpp
namespace NClipboard {
    void copy(std::string data);
};
```

```cpp
void copy(std::string data);
```

```cpp
#include "src/clipboard/Clipboard.hpp"

std::string hexColor = "#FF5733";
NClipboard::copy(hexColor);  // Non-blocking, returns immediately
```

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

### Get HSV Color Output

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CColor.md

Demonstrates retrieving a CColor object and converting its components to HSV values, then formatting them into a string with percentages for S and V. Assumes getColorFromPixel and getHSV are available.

```cpp
CColor color = getColorFromPixel(surface, position);
float h, s, v;
color.getHSV(h, s, v);
std::string hsv = std::format("%d %d%% %d%%", (int)h, (int)s, (int)v);
// Example: 11 100% 100%
```

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

### Get HSL Color Output

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CColor.md

Shows how to obtain a CColor object and convert its components to HSL values, then format them into a string with percentages for S and L. Assumes getColorFromPixel and getHSL are available.

```cpp
CColor color = getColorFromPixel(surface, position);
float h, s, l;
color.getHSL(h, s, l);
std::string hsl = std::format("%d %d%% %d%%", (int)h, (int)s, (int)l);
// Example: 11 100% 60%
```

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

### Get CMYK Color Output

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CColor.md

Illustrates obtaining a CColor object and converting its components to CMYK values, then formatting them into a percentage string. Assumes getColorFromPixel and getCMYK are available.

```cpp
CColor color = getColorFromPixel(surface, position);
float c, m, y, k;
color.getCMYK(c, m, y, k);
std::string cmyk = std::format("%d%% %d%% %d%% %d%%", (int)c, (int)m, (int)y, (int)k);
// Example: 0% 66% 80% 0%
```

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

### Wayland Callback Example: Monitor Geometry Changes

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/module-structure.md

This snippet demonstrates how to set a callback for monitor geometry changes using the Wayland interface. It captures the 'this' pointer to access class members.

```cpp
output->setGeometry([this](CCWlOutput* r, ...) { /* update size */ });
```

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

### initKeyboard()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Sets up keyboard input listeners and XKB keymap. This function is called automatically when keyboard capability is detected.

```APIDOC
## initKeyboard()

### Description
Sets up keyboard input listeners and XKB keymap. Called automatically when keyboard capability is detected.

### Method
void

### Parameters
None

### Response
#### Success Response (void)
void

### Request Example
```cpp
initKeyboard();
```

### Response Example
```cpp
// void return type
```
```

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

### Initialize Hyprpicker Application

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/quick-reference.md

Application startup involves creating and initializing the CHyprpicker instance. Configuration options like output mode, format, and auto-copy can be set before initialization.

```cpp
// Application startup
g_pHyprpicker = std::make_unique<CHyprpicker>();
g_pHyprpicker->init();  // Blocks until color picked or SIGTERM

// Configuration before init()
g_pHyprpicker->m_bSelectedOutputMode = OUTPUT_RGB;
g_pHyprpicker->m_sOutputFormat = "rgb({0}, {1}, {2})";
g_pHyprpicker->m_bAutoCopy = true;
```

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

### Initialize Keyboard Input

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Sets up keyboard input listeners and XKB keymap. Called automatically when keyboard capability is detected.

```cpp
void initKeyboard();
```

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

### Display Version Information

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Use the -V or --version flags to print the application's version string and exit. The version is determined at build time.

```sh
hyprpicker --version
```

```sh
hyprpicker -V
```

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

### Typical Usage Patterns for Logging

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-utilities.md

Illustrates common scenarios for using the Debug::log function, such as checking for feature availability, handling critical failures, debugging with trace messages, and outputting color values.

```cpp
// Check if feature is available
if (!m_pCursorShapeMgr)
    Debug::log(ERR, "cursor_shape_v1 not supported, cursor won't be affected");

// Critical failure - exit immediately
if (!m_pScreencopyMgr) {
    Debug::log(CRIT, "zwlr_screencopy_v1 not supported, can't proceed");
    exit(1);
}

// Trace for debugging
Debug::log(TRACE, "renderSurface: scalebufs %.2fx%.2f", scaleX, scaleY);

// Output the color
Debug::log(NONE, formattedColor.c_str());
```

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

### initMouse()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Sets up mouse pointer input listeners. This function is called automatically when pointer capability is detected.

```APIDOC
## initMouse()

### Description
Sets up mouse pointer input listeners. Called automatically when pointer capability is detected.

### Method
void

### Parameters
None

### Response
#### Success Response (void)
void

### Request Example
```cpp
initMouse();
```

### Response Example
```cpp
// void return type
```
```

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

### Initialize CLayerSurface

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CLayerSurface.md

Initializes a new CLayerSurface for a given monitor. This involves creating a Wayland surface, requesting viewport and fractional scale support, and binding to the layer shell for overlay positioning. Ensure a valid SMonitor pointer is provided.

```cpp
SMonitor* monitor = g_pHyprpicker->m_vMonitors[0].get();
auto surface = std::make_unique<CLayerSurface>(monitor);
```

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

### Initialize SMonitor with Wayland Output

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SMonitor.md

Demonstrates the instantiation of an SMonitor object using a Wayland output proxy. This is typically called during Wayland registry enumeration when a new output is detected.

```cpp
auto output = makeShared<CCWlOutput>(/* ... */);
auto monitor = std::make_unique<SMonitor>(output);
```

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

### Hyprpicker Rendering Workflow

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SPoolBuffer.md

This workflow demonstrates how to obtain a buffer, draw to it using Cairo, and submit it for rendering. Ensure to flush the Cairo surface before submitting and wait for the buffer release callback.

```cpp
// 1. Get an available (non-busy) buffer
SP<SPoolBuffer> buffer = g_pHyprpicker->getBufferForLS(layerSurface);

// 2. Create Cairo surface for drawing
buffer->surface = cairo_image_surface_create_for_data(
    (unsigned char*)buffer->data,
    CAIRO_FORMAT_ARGB32,
    buffer->pixelSize.x,
    buffer->pixelSize.y,
    buffer->pixelSize.x * 4
);

// 3. Create Cairo context
buffer->cairo = cairo_create(buffer->surface);

// 4. Draw the zoom lens
cairo_set_source_rgba(buffer->cairo, 0, 0, 0, 0);
cairo_rectangle(buffer->cairo, 0, 0, buffer->pixelSize.x, buffer->pixelSize.y);
cairo_fill(buffer->cairo);
// ... more drawing ...

// 5. Flush Cairo to sync with buffer
cairo_surface_flush(buffer->surface);

// 6. Submit to Wayland
layerSurface->sendFrame();

// 7. Wait for release callback (sets busy = false)
```

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

### Get Available Render Buffer from Layer Surface

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Retrieves a non-busy render buffer from a layer surface's double buffer pool. Returns nullptr if no buffer is available.

```cpp
SP<SPoolBuffer> getBufferForLS(CLayerSurface* pLS);
```

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

### Initialize Mouse Input

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Sets up mouse pointer input listeners. Called automatically when pointer capability is detected.

```cpp
void initMouse();
```

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

### Typical Rendering Workflow for CLayerSurface

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CLayerSurface.md

This snippet illustrates the standard sequence for rendering and submitting frames using a CLayerSurface. It involves obtaining a buffer, rendering content to it, and then submitting the frame to Wayland for display.

```cpp
// 1. Get an available buffer
SP<SPoolBuffer> buffer = g_pHyprpicker->getBufferForLS(surface);

// 2. Render to it (Cairo drawing)
g_pHyprpicker->renderSurface(surface);

// 3. Submit to Wayland
surface->sendFrame();

// 4. Wait for frame callback, then loop back to step 1
```

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

### Get Color From Pixel - Hyprpicker API

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Extracts the RGBA color value from a specific pixel within a given layer surface's captured frame. Requires the layer surface and the pixel coordinates.

```cpp
CColor getColorFromPixel(CLayerSurface* pLS, Vector2D pos);
```

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

### createPoolFile()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Creates a temporary file in XDG_RUNTIME_DIR using mkstemp for use as Wayland shared memory backing. Sets close-on-exec flag for safety.

```APIDOC
## createPoolFile()

### Description
Creates a temporary file in XDG_RUNTIME_DIR using mkstemp for use as Wayland shared memory backing. Sets close-on-exec flag for safety.

### Method
`int createPoolFile(size_t size, std::string& name);`

### Parameters
#### Path Parameters
- **size** (size_t) - Required - Size in bytes to allocate
- **name** (std::string&) - Required - Output parameter: path to created file in XDG_RUNTIME_DIR

### Response
#### Success Response
- **Returns:** `int` - File descriptor for the created memory-mapped file, or -1 on failure
```

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

### Display Help Message

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Use the -h or --help flags to display the help message and exit. This is useful for understanding all available options.

```sh
hyprpicker --help
```

```sh
hyprpicker -h
```

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

### Initialize Screencopy Frame

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SMonitor.md

Initializes a new screencopy frame by capturing output from a monitor. This is the first step in the screencopy process.

```cpp
mon->pSCFrame = makeShared<CCZwlrScreencopyFrameV1>(
    m_pScreencopyMgr->sendCaptureOutput(includesCursor, mon->output->resource())
);

```

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

### CLayerSurface Constructor

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CLayerSurface.md

Initializes a new CLayerSurface for a given monitor. This involves creating Wayland surface objects, setting up necessary protocols like viewport and fractional scale, and configuring the layer surface for overlay display.

```APIDOC
## CLayerSurface Constructor

### Description
Initializes a new layer surface for the given monitor. Creates a Wayland surface, requests viewport and fractional scale if supported, and binds to the layer shell for overlay positioning.

### Parameters
#### Path Parameters
- **pMonitor** (SMonitor*) - Required - The monitor this surface is bound to

### Behavior
1. Creates a new wl_surface via the compositor
2. Optionally creates viewport and fractional scale listeners (if protocols are available)
3. Gets a layer surface from the layer shell protocol (OVERLAY layer)
4. Sets surface configuration (fullscreen, exclusive zone -1, keyboard interactive)
5. Commits the surface to make it visible

### Returns
Properly initialized CLayerSurface object

### Throws
Calls `CHyprpicker::finish(1)` if:
- Compositor doesn't allow surface creation
- Compositor doesn't allow layer surface creation

### Example
```cpp
SMonitor* monitor = g_pHyprpicker->m_vMonitors[0].get();
auto surface = std::make_unique<CLayerSurface>(monitor);
```
```

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

### Enable Desktop Notifications

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Sends a desktop notification with the picked color when a color is selected. Requires notify-send and a notification daemon.

```sh
hyprpicker --notify                # Pick color and show notification
```

```sh
hyprpicker -n                       # Short form
```

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

### Global State Access: Outputting Color

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/module-structure.md

This snippet demonstrates accessing the global `g_pHyprpicker` pointer from a mouse click handler to trigger the output of color information.

```cpp
g_pHyprpicker->outputColor();             // Mouse click handler
```

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

### Create SPoolBuffer Instance

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SPoolBuffer.md

Instantiates an SPoolBuffer with specified pixel dimensions, format, and stride. Ensure format and stride are correctly calculated for the desired pixel format.

```cpp
Vector2D size{1920, 1080};
uint32_t format = WL_SHM_FORMAT_ARGB8888;
uint32_t stride = 1920 * 4;  // 4 bytes per pixel

auto pool_buffer = makeShared<SPoolBuffer>(size, format, stride);
```

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

### SMonitor Struct Methods

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/quick-reference.md

Methods for initializing and managing monitor information.

```APIDOC
## SMonitor Struct Methods

### Description
Methods for initializing and managing monitor-specific data.

### Methods
- `SMonitor(SP<CCWlOutput> output_)`: Constructor for SMonitor, taking a Wayland output pointer.
- `initSCFrame()`: Initializes the screencopy frame for the monitor.
```

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

### Hyprpicker Main Application Module Dependencies

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/module-structure.md

The main application module depends on various helper, utility, and system modules. It requires logging, layer surface management, buffer management, clipboard, and notification functionalities. It also relies on Wayland protocols and the XKBCommon library.

```cpp
#include "defines.hpp"
#include "debug/Log.hpp"
#include "helpers/LayerSurface.hpp"
#include "helpers/PoolBuffer.hpp"
#include "clipboard/Clipboard.hpp"
#include "notify/Notify.hpp"
```

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

### Scripting Color Selection

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Integrate hyprpicker into shell scripts by capturing its output. Use flags like --no-fancy and -q for clean, script-friendly output.

```sh
#!/bin/bash
COLOR=$(hyprpicker -f hex --no-fancy -q)
echo "Selected color: $COLOR"
```

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

### Custom Output Format String

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Use the --output-format or -o option with a printf-style format string to customize the color output. Placeholders are numbered {0}, {1}, etc. The format string is validated at startup.

```sh
# RGB with custom formatting
hyprpicker -f rgb -o "rgb({0}, {1}, {2})"
# Output: rgb(255, 87, 51)
```

```sh
# HSL with different format
hyprpicker -f hsl -o "hsl({0} {1}% {2}%)"
# Output: hsl(11 100% 60%)
```

```sh
# CMYK with percent signs
hyprpicker -f cmyk -o "C:{0}% M:{1}% Y:{2}% K:{3}%"
# Output: C:0% M:66% Y:80% K:0%
```

```sh
# Hex uppercase (default)
hyprpicker -f hex -o "#{0}{1}{2}"
# Output: #FF5733
```

```sh
# Hex with custom spacing
hyprpicker -f hex -o "{0}:{1}:{2}"
# Output: FF:57:33
```

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

### Initialize Screencopy Frame Listener

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SMonitor.md

Sets up listeners for screencopy frame data. This method should be called after initializing the screencopy frame and is responsible for handling buffer updates, flags, and readiness notifications.

```cpp
void initSCFrame();
```

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

### Basic Color Picker Usage

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Run hyprpicker without any arguments for basic functionality. The default output is the selected color in uppercase hex format with color codes.

```sh
hyprpicker
# Output: #FF5733 (hex format, uppercase, with color codes)
```

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

### CHyprpicker Class Methods

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/quick-reference.md

Provides an overview of the methods available in the CHyprpicker class for initializing, rendering, and managing the Hyprpicker application.

```APIDOC
## CHyprpicker Class Methods

### Description
Methods for initializing, rendering surfaces, outputting color information, and managing internal state.

### Methods
- `init()`: Initializes the Hyprpicker application.
- `finish(int code = 0)`: Finishes the Hyprpicker application with an exit code.
- `renderSurface(CLayerSurface*, bool forceInactive = false)`: Renders a given layer surface, optionally forcing it to be inactive.
- `outputColor()`: Outputs the current color information.
- `recheckACK()`: Rechecks the acknowledgment status.
- `markDirty()`: Marks the internal state as dirty, requiring a re-render.
- `createPoolFile(size_t, std::string&)`: Creates a pool file with specified size and returns its file descriptor.
- `setCloexec(const int&)`: Sets the close-on-exec flag for a given file descriptor.
- `getBufferForLS(CLayerSurface*)`: Retrieves a buffer for a given layer surface.
- `convertBuffer(SP<SPoolBuffer>)`: Converts a pool buffer.
- `convert24To32Buffer(SP<SPoolBuffer>)`: Converts a 24-bit buffer to a 32-bit buffer.
- `getColorFromPixel(CLayerSurface*, Vector2D)`: Gets the color from a pixel at specified coordinates on a layer surface.
- `initKeyboard()`: Initializes keyboard input.
- `initMouse()`: Initializes mouse input.
```

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

### RGB Output with Notification

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Use the -f rgb flag for RGB output and the -n flag to display a desktop notification with the selected color. The output format is R G B.

```sh
hyprpicker -f rgb -n
# Output: 255 87 51
# Shows desktop notification with the color
```

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

### Handle Missing XDG_RUNTIME_DIR

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

The application requires XDG_RUNTIME_DIR to be set for Wayland buffer management. If not set, it will exit with a critical error.

```sh
[CRITICAL] XDG_RUNTIME_DIR not set!
```

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

### Enable Autocopy to Clipboard

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Automatically copies the formatted color value to the clipboard using wl-copy. Requires the wl-clipboard package.

```sh
hyprpicker --autocopy              # Pick color and copy to clipboard
```

```sh
hyprpicker -a                       # Short form
```

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

### Define Color Output Modes (eOutputMode)

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Defines the supported color output formats. Select the desired mode using the `--format` or `-f` command-line option.

```cpp
enum eOutputMode : uint8_t {
    OUTPUT_CMYK = 0,
    OUTPUT_HEX,
    OUTPUT_RGB,
    OUTPUT_HSL,
    OUTPUT_HSV,
};
```

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

### SMonitor Constructor

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SMonitor.md

Initializes the SMonitor object with a Wayland output proxy and sets up listeners for output property changes. This is called during Wayland registry enumeration when a new output is bound.

```APIDOC
## SMonitor Constructor

### Description
Initializes monitor state and sets up listeners for output property changes. Called when a new output is bound during Wayland registry enumeration.

### Parameters
#### Path Parameters
- **output_** (SP<CCWlOutput>) - Required - Wayland output (display) proxy

### Request Example
```cpp
auto output = makeShared<CCWlOutput>(/* ... */);
auto monitor = std::make_unique<SMonitor>(output);
```
```

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

### Enable Verbose Logging with hyprpicker

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Use the --verbose or -v flag to enable verbose (TRACE level) logging. This provides detailed information useful for debugging, including frame capture, buffer operations, and coordinate transformations.

```sh
hyprpicker --verbose               # Verbose logging

```

```sh
hyprpicker -v                       # Short form

```

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

### Scale and Configuration

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CLayerSurface.md

Manages the fractional scale factor, acknowledgment of configuration changes, and flags for reloading buffers due to scale changes. Includes the serial number for acknowledging layer surface configurations.

```cpp
float fractionalScale = 1.F;
bool wantsACK = false;
bool wantsReload = false;
uint32_t ACKSerial = 0;
```

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

### Create Screen Buffers

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SPoolBuffer.md

Screen buffers are created to hold screencopy data. They are initialized with capture dimensions, format, and stride.

```cpp
pLS->screenBuffer = makeShared<SPoolBuffer>(captureSize, captureFormat, captureStride);
```

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

### Create Memory-Mapped Pool File

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Creates a temporary file in XDG_RUNTIME_DIR for Wayland shared memory. The file descriptor is returned, and the caller is responsible for managing the file.

```cpp
int createPoolFile(size_t size, std::string& name);
```

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

### Custom Format with Quiet Output

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Specify a custom output format using -f and a format string, and use -q for quiet output, which suppresses logging and only outputs the color.

```sh
hyprpicker -f rgb -o "rgb({0},{1},{2})" -q
# Output: rgb(255,87,51)
# No logging, only the color
```

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

### Set Output Format

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/configuration.md

Use the --format or -f option to specify the color output format. Supported formats include cmyk, hex, rgb, hsl, and hsv.

```sh
hyprpicker --format=rgb        # Output as RGB
hyprpicker -f cmyk             # Output as CMYK
```

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

### CColor Class Methods

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/quick-reference.md

Methods for retrieving color components in different color spaces.

```APIDOC
## CColor Class Methods

### Description
Methods to extract color information in various color models.

### Methods
- `getCMYK(float& c, float& m, float& y, float& k) const`: Gets the CMYK color components.
- `getHSV(float& h, float& s, float& v) const`: Gets the HSV color components.
- `getHSL(float& h, float& s, float& l) const`: Gets the HSL color components.
```

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

### Define Weak Pointer Macro Alias

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Creates a macro alias 'WP' for 'CWeakPointer' from the hyprutils library, used for non-owning smart pointers.

```cpp
#define WP CWeakPointer
```

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

### renderSurface

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Renders the overlay surface with the zoom lens and screen capture. Performs Cairo drawing to create the magnified lens view centered on the mouse cursor. Only shows the zoom lens on the active (last interacted) surface.

```APIDOC
## renderSurface()

### Description
Renders the overlay surface with the zoom lens and screen capture. Performs Cairo drawing to create the magnified lens view centered on the mouse cursor. Only shows the zoom lens on the active (last interacted) surface.

### Method
void

### Parameters
#### Path Parameters
- `pSurface` (CLayerSurface*) - Required - The layer surface to render
- `forceInactive` (bool) - Optional - If true, render without the zoom lens (Default: false)

### Request Example
```cpp
g_pHyprpicker->renderSurface(m_pLastSurface);
```

### Response
#### Success Response (void)
void

#### Response Example
(No specific response body example provided)
```

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

### Include Direct Wayland Protocols

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/module-structure.md

Includes C++ wrapper classes generated from Wayland XML protocol definitions. These are essential for Wayland-specific functionalities.

```cpp
#include "protocols/cursor-shape-v1.hpp"
#include "protocols/fractional-scale-v1.hpp"
#include "protocols/wlr-layer-shell-unstable-v1.hpp"
#include "protocols/wlr-screencopy-unstable-v1.hpp"
#include "protocols/viewporter.hpp"
#include "protocols/wayland.hpp"
```

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

### Hyprpicker Color Picking Logic

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/quick-reference.md

This function outlines the process of capturing a color from a pixel, converting it to HSV, formatting it according to user preferences, and handling optional features like auto-copy and notifications.

```cpp
// User clicks -> outputColor() is called
void outputColor() {
    // Get color at m_vLastCoords from m_pLastSurface
    CColor col = getColorFromPixel(m_pLastSurface, clickPos);
    
    // Convert to output format
    float h, s, v;
    col.getHSV(h, s, v);
    
    // Format and output
    std::string result = std::vformat(m_sOutputFormat, std::make_format_args(h, s, v));
    Debug::log(NONE, result.c_str());
    
    // Optional features
    if (m_bAutoCopy) NClipboard::copy(result);
    if (m_bNotify) NNotify::send(hexColor, result);
    
    finish();
}
```

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

### recheckACK()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Checks all layer surfaces for pending configure acknowledgments and buffer size changes. Acknowledges layer surface configure events and creates new render buffers if needed.

```APIDOC
## recheckACK()

### Description
Checks all layer surfaces for pending configure acknowledgments and buffer size changes. Acknowledges layer surface configure events and creates new render buffers if needed.

### Method
`void recheckACK();`

### Response
#### Success Response
- **Returns:** `void`
```

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

### Send desktop notification

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-utilities.md

Sends a desktop notification displaying the picked color with visual feedback using the `notify-send` command. This function is non-blocking; it spawns a process and returns immediately. If `notify-send` is not available, the operation fails silently.

```cpp
namespace NNotify {
    void send(std::string hexColor, std::string formattedColor);
};
```

```cpp
void send(std::string hexColor, std::string formattedColor);
```

```cpp
#include "src/notify/Notify.hpp"

std::string hex = "#FF5733";
std::string rgb = "255 87 51";
NNotify::send(hex, rgb);  // Shows notification, returns immediately
```

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

### Create Render Buffers

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-SPoolBuffer.md

Render buffers are created for layer surface rendering. They are initialized with monitor dimensions and ARGB8888 format.

```cpp
buffers[0] = makeShared<SPoolBuffer>(monitorSize, WL_SHM_FORMAT_ARGB8888, monitorSize.x * 4);
buffers[1] = makeShared<SPoolBuffer>(monitorSize, WL_SHM_FORMAT_ARGB8888, monitorSize.x * 4);
```

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

### Wayland Output Transformations

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/types.md

Defines possible output transformation states for Wayland compositors, including rotation and flipping. Used to apply monitor rotation and flipping.

```cpp
enum wl_output_transform {
    WL_OUTPUT_TRANSFORM_NORMAL = 0,
    WL_OUTPUT_TRANSFORM_90 = 1,
    WL_OUTPUT_TRANSFORM_180 = 2,
    WL_OUTPUT_TRANSFORM_270 = 3,
    WL_OUTPUT_TRANSFORM_FLIPPED = 4,
    WL_OUTPUT_TRANSFORM_FLIPPED_90 = 5,
    WL_OUTPUT_TRANSFORM_FLIPPED_180 = 6,
    WL_OUTPUT_TRANSFORM_FLIPPED_270 = 7,
};
```

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

### Render Layer Surface - Hyprpicker API

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CHyprpicker.md

Renders a specific layer surface, optionally forcing an inactive state. Used for drawing the overlay with a zoom lens and screen capture.

```cpp
void renderSurface(CLayerSurface* pSurface, bool forceInactive = false);
```

```cpp
g_pHyprpicker->renderSurface(m_pLastSurface);
```

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

### Monitor Module Dependencies

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/module-structure.md

The Monitor module depends on the main application controller, layer surface management, Wayland protocols, the Cairo library, and the Hyprutils math library.

```cpp
#include "hyprpicker.hpp"
#include "helpers/LayerSurface.hpp"

// Wayland protocols, Cairo library, Hyprutils math library
```

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

### CLayerSurface Constructor

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CLayerSurface.md

Constructs a CLayerSurface object, binding it to a specific monitor. This is used to create an overlay surface for rendering elements like zoom lenses and color previews.

```cpp
CLayerSurface(SMonitor* pMonitor);
```

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

### Buffer Management

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CLayerSurface.md

Handles double buffering and screen capture. This includes indices for the last submitted buffer, render buffers, the screen capture buffer, screencopy flags and format, and a pending frame callback listener.

```cpp
int lastBuffer;
SP<SPoolBuffer> buffers[2];
SP<SPoolBuffer> screenBuffer;
uint32_t scflags;
uint32_t screenBufferFormat;
SP<CCWlCallback> frameCallback;
```

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

### getCMYK()

Source: https://github.com/hyprwm/hyprpicker/blob/main/_autodocs/api-reference-CColor.md

Converts the current RGBA color to its CMYK representation. The results are outputted as percentages (0-100%) via reference parameters.

```APIDOC
## getCMYK()

### Description
Converts the RGB color to CMYK color space. Implements the standard RGB-to-CMYK conversion formula where CMYK values are normalized to percentages (0-100).

### Method
`void getCMYK(float& c, float& m, float& y, float& k) const`

### Parameters
#### Out Parameters
- **c** (float&) - Cyan component (0-100%)
- **m** (float&) - Magenta component (0-100%)
- **y** (float&) - Yellow component (0-100%)
- **k** (float&) - Key (black) component (0-100%)

### Returns
`void` (results written to output parameters)

### Example
```cpp
CColor color{.r = 255, .g = 87, .b = 51};
float c, m, y, k;
color.getCMYK(c, m, y, k);
// Results: c = 0, m = 66, y = 80, k = 0 (percentages)
```
```