### Build and Install GdkPixbuf with Meson

Source: https://github.com/gnome/gdk-pixbuf/blob/master/README.md

Configure, build, and install GdkPixbuf using Meson. Ensure you have the necessary build requirements installed.

```sh
meson setup _build .
meson compile -C _build
meson install -C _build
```

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

### Build GdkPixbuf Library with Meson

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Commands to set up, compile, and install the GdkPixbuf library using Meson. This is typically done from source.

```bash
# Build the library from source
meson setup _build . --prefix=/usr
meson compile -C _build
meson install -C _build
```

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

### Meson Build Integration for GdkPixbuf

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Example Meson build file (`meson.build`) demonstrating how to declare a dependency on GdkPixbuf and link it to an executable.

```meson
# meson.build
project('my-app', 'c')

gdk_pixbuf_dep = dependency('gdk-pixbuf-2.0', version: '>= 2.42')

executable('my-app', 'main.c',
  dependencies: [gdk_pixbuf_dep])
```

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

### Compile Application with GdkPixbuf using GCC

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Compile a single C file application against an installed GdkPixbuf library using GCC and pkg-config to automatically determine compiler and linker flags.

```bash
# Compile a single-file program against the installed library
gcc my_app.c \
    $(pkg-config --cflags --libs gdk-pixbuf-2.0) \
    -o my_app
```

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

### `gdk_pixbuf_add_alpha` — Add or promote an alpha channel

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Returns a new pixbuf that has an alpha channel. If `substitute_color` is `TRUE`, pixels matching the RGB triple `(r, g, b)` are made fully transparent (color-keying); otherwise all pixels get full opacity.

```APIDOC
## `gdk_pixbuf_add_alpha` — Add or promote an alpha channel

Returns a new pixbuf that has an alpha channel. If `substitute_color` is `TRUE`, pixels matching the RGB triple `(r, g, b)` are made fully transparent (color-keying); otherwise all pixels get full opacity.

### Parameters

*   **pixbuf** (*GdkPixbuf*): The source pixbuf.
*   **substitute_color** (*gboolean*): If `TRUE`, pixels matching `(r, g, b)` are made transparent.
*   **r** (*guchar*): Red component of the color to substitute.
*   **g** (*guchar*): Green component of the color to substitute.
*   **b** (*guchar*): Blue component of the color to substitute.

### Returns

*   (*GdkPixbuf*): A new pixbuf with an alpha channel, or `NULL` on error.

### Request Example
```c
GError *error = NULL;
GdkPixbuf *rgb = gdk_pixbuf_new_from_file ("opaque.bmp", &error);
g_assert_no_error (error);

/* Promote to RGBA, making pure white (255,255,255) transparent */
GdkPixbuf *rgba = gdk_pixbuf_add_alpha (rgb, TRUE, 255, 255, 255);
g_assert_cmpint (gdk_pixbuf_get_n_channels (rgba), ==, 4);
g_assert_true  (gdk_pixbuf_get_has_alpha (rgba));

gdk_pixbuf_save (rgba, "transparent.png", "png", &error, NULL);
g_assert_no_error (error);

g_object_unref (rgba);
g_object_unref (rgb);
```
```

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

### Configure and Build GdkPixbuf Documentation

Source: https://github.com/gnome/gdk-pixbuf/blob/master/CONTRIBUTING.md

Enable documentation building by configuring Meson with the 'docs' option and then building the 'gdk-pixbuf-doc' target.

```sh
$ cd _build
$ meson configure -Ddocs=true
$ ninja
$ ninja gdk-pixbuf-doc
```

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

### Core GdkPixbuf Functionalities

Source: https://github.com/gnome/gdk-pixbuf/blob/master/docs/gdk-pixbuf-sections.txt

Core functions for interacting with GdkPixbuf objects, including getting image properties and manipulating pixel data.

```APIDOC
## Core GdkPixbuf Functions

### Information Retrieval
- `gdk_pixbuf_get_colorspace`: Gets the colorspace of the pixbuf.
- `gdk_pixbuf_get_n_channels`: Gets the number of color channels.
- `gdk_pixbuf_get_has_alpha`: Checks if the pixbuf has an alpha channel.
- `gdk_pixbuf_get_bits_per_sample`: Gets the number of bits per color sample.
- `gdk_pixbuf_get_width`: Gets the width of the pixbuf.
- `gdk_pixbuf_get_height`: Gets the height of the pixbuf.
- `gdk_pixbuf_get_rowstride`: Gets the rowstride (bytes per row).
- `gdk_pixbuf_get_byte_length`: Gets the total byte length of the pixel data.

### Pixel Data Access
- `gdk_pixbuf_get_pixels`: Gets a pointer to the raw pixel data.
- `gdk_pixbuf_get_pixels_with_length`: Gets a pointer to the raw pixel data and its length.
- `gdk_pixbuf_read_pixels`: Reads pixel data into a buffer.
- `gdk_pixbuf_read_pixel_bytes`: Reads pixel data as a `GBytes`.

### Option Handling
- `gdk_pixbuf_get_option`: Gets a specific option from the pixbuf.
- `gdk_pixbuf_set_option`: Sets an option on the pixbuf.
- `gdk_pixbuf_remove_option`: Removes an option from the pixbuf.
- `gdk_pixbuf_get_options`: Gets all options from the pixbuf.
- `gdk_pixbuf_copy_options`: Copies options from one pixbuf to another.

### Rowstride Calculation
- `gdk_pixbuf_calculate_rowstride`: Calculates the rowstride for a given width and number of channels.
```

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

### Git Commit Author Option Example

Source: https://github.com/gnome/gdk-pixbuf/blob/master/CONTRIBUTING.md

Use the --author option with git commit to specify the author of the commit when committing on behalf of others. Include --signoff.

```bash
git commit -a --author "Joe Coder <joe@coder.org>" --signoff
```

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

### Enable GTK Documentation Build Option

Source: https://github.com/gnome/gdk-pixbuf/blob/master/README.md

Build the API reference documentation for GdkPixbuf by setting the -Dgtk_doc option to true during Meson configuration.

```sh
meson setup _build . -Dgtk_doc=true
```

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

### Build GdkPixbuf Locally

Source: https://github.com/gnome/gdk-pixbuf/blob/master/CONTRIBUTING.md

Build the GdkPixbuf library using Meson and Ninja. This involves configuring the build and then compiling the project.

```sh
$ meson _build .
$ cd _build
$ ninja
```

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

### Run GdkPixbuf Test Suite

Source: https://github.com/gnome/gdk-pixbuf/blob/master/README.md

Execute the test suite for GdkPixbuf by running 'meson test' within the build directory.

```sh
meson test -C _build
```

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

### Load and Fit Pixbuf to Size

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads an image and scales it to fit within a bounding box while always preserving the original aspect ratio. Ideal for icon generation.

```c
GError *error = NULL;

/* Fit into a 128×128 icon slot */
GdkPixbuf *icon = gdk_pixbuf_new_from_file_at_size ("logo.svg", 128, 128, &error);
if (icon == NULL) {
    g_warning ("Could not load icon: %s", error->message);
    g_error_free (error);
} else {
    g_print ("Icon size: %d×%d\n",
             gdk_pixbuf_get_width (icon),
             gdk_pixbuf_get_height (icon));
    g_object_unref (icon);
}
```

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

### Run GdkPixbuf Test Suite

Source: https://github.com/gnome/gdk-pixbuf/blob/master/CONTRIBUTING.md

Execute the test suite to ensure no regressions are introduced and to verify bug fixes or new features.

```sh
$ cd _build
$ meson test
```

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

### Load and Scale Pixbuf from File

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads an image from a file and scales it to fit within specified dimensions, optionally preserving aspect ratio. Useful for creating thumbnails.

```c
GError *error = NULL;

/* Scale to at most 256×256, preserving aspect ratio */
GdkPixbuf *thumb = gdk_pixbuf_new_from_file_at_scale (
    "large-photo.jpg",
    256, 256,
    TRUE,   /* preserve_aspect_ratio */
    &error);

if (thumb == NULL) {
    g_printerr ("Error: %s\n", error->message);
    g_error_free (error);
} else {
    /* Actual dimensions will respect the original aspect ratio,
     * e.g. a 1600×900 source becomes 256×144 */
    g_print ("Thumbnail: %d×%d\n",
             gdk_pixbuf_get_width (thumb),
             gdk_pixbuf_get_height (thumb));
    g_object_unref (thumb);
}
```

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

### Enable Relocatable Application Bundle Support

Source: https://github.com/gnome/gdk-pixbuf/blob/master/README.md

Enable support for application bundle relocation by setting the -Drelocatable option to true during Meson configuration.

```sh
meson setup _build . -Drelocatable=true
```

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

### Enumerate and Probe GdkPixbuf Formats

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Use `gdk_pixbuf_get_formats` to list all available image formats and their properties. Use `gdk_pixbuf_get_file_info` to identify a file's format and dimensions without full decoding.

```c
/* List all registered image formats */
GSList *formats = gdk_pixbuf_get_formats ();
for (GSList *l = formats; l != NULL; l = l->next) {
    GdkPixbufFormat *fmt = l->data;
    gchar  *name  = gdk_pixbuf_format_get_name (fmt);
    gchar  *desc  = gdk_pixbuf_format_get_description (fmt);
    gchar **exts  = gdk_pixbuf_format_get_extensions (fmt);
    gboolean writable = gdk_pixbuf_format_is_writable (fmt);

    g_print ("%-10s  %-30s  writable=%s  exts:", name, desc,
             writable ? "yes" : "no ");
    for (int i = 0; exts[i]; i++)
        g_print (" .%s", exts[i]);
    g_print ("\n");

    g_free (name); g_free (desc); g_strfreev (exts);
}
g_slist_free (formats);

/* Probe a file's format and dimensions without full decode */
gint probe_w = 0, probe_h = 0;
GdkPixbufFormat *fmt = gdk_pixbuf_get_file_info ("unknown.img", &probe_w, &probe_h);
if (fmt) {
    gchar *name = gdk_pixbuf_format_get_name (fmt);
    g_print ("Detected: %s, %d×%d\n", name, probe_w, probe_h);
    g_free (name);
} else {
    g_print ("Unknown image format\n");
}
```

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

### Pixbuf options — Attach and read key/value metadata

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Format loaders attach metadata (e.g., ICC profiles, EXIF orientation, PNG text chunks) as string options. Applications can read, set, copy, and remove these options. Option keys for PNG text chunks use the `"tEXt::"` prefix.

```APIDOC
## Pixbuf options — Attach and read key/value metadata

Format loaders attach metadata (e.g., ICC profiles, EXIF orientation, PNG text chunks) as string options. Applications can read, set, copy, and remove these options. Option keys for PNG text chunks use the `"tEXt::"` prefix.

### `gdk_pixbuf_get_option`

Gets the value of an option associated with the pixbuf.

### `gdk_pixbuf_set_option`

Sets an option associated with the pixbuf.

### `gdk_pixbuf_remove_option`

Removes an option associated with the pixbuf.

### `gdk_pixbuf_copy_options`

Copies all options from one pixbuf to another.

### `gdk_pixbuf_get_options`

Returns a hash table containing all options associated with the pixbuf.

### Request Example
```c
GError *error = NULL;
GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file ("photo.jpg", &error);
g_assert_no_error (error);

/* Read EXIF orientation written by the JPEG loader */
const gchar *orient = gdk_pixbuf_get_option (pixbuf, "orientation");
if (orient)
    g_print ("EXIF orientation: %s\n", orient);

/* Set a custom option */
gdk_pixbuf_set_option (pixbuf, "tEXt::Software", "MyApp 1.0");

/* Copy all options to another pixbuf */
GdkPixbuf *copy = gdk_pixbuf_copy (pixbuf);
gdk_pixbuf_copy_options (pixbuf, copy);
g_print ("Software option on copy: %s\n",
         gdk_pixbuf_get_option (copy, "tEXt::Software"));

/* Remove an option */
gdk_pixbuf_remove_option (copy, "tEXt::Software");
g_assert_null (gdk_pixbuf_get_option (copy, "tEXt::Software"));

/* Enumerate all options */
GHashTable *opts = gdk_pixbuf_get_options (pixbuf);
GHashTableIter iter;
gpointer key, value;
g_hash_table_iter_init (&iter, opts);
while (g_hash_table_iter_next (&iter, &key, &value))
    g_print ("  option: %s = %s\n", (gchar *)key, (gchar *)value);

g_object_unref (copy);
g_object_unref (pixbuf);
```
```

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

### Standard Commit Message Format

Source: https://github.com/gnome/gdk-pixbuf/blob/master/CONTRIBUTING.md

Follow this format for all commit messages. Ensure the first line is a concise summary, followed by a more detailed explanation and issue closing references.

```plain
Short explanation of the commit

Longer explanation explaining exactly what’s changed, whether any
external or private interfaces changed, what bugs were fixed (with bug
tracker reference if applicable) and so forth. Be concise but not too
brief.

Closes #1234
```

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

### Copy and Crop GdkPixbuf Images

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Use `gdk_pixbuf_copy` for a deep copy and `gdk_pixbuf_new_subpixbuf` for a zero-copy crop view. Modifying a subpixbuf modifies the original.

```c
GError *error = NULL;
GdkPixbuf *original = gdk_pixbuf_new_from_file ("photo.png", &error);
g_assert_no_error (error);

/* Deep copy */
GdkPixbuf *copy = gdk_pixbuf_copy (original);

/* Zero-copy 200×200 crop starting at (50, 30) */
GdkPixbuf *crop = gdk_pixbuf_new_subpixbuf (original, 50, 30, 200, 200);

g_print ("Original: %d×%d\n", gdk_pixbuf_get_width (original), gdk_pixbuf_get_height (original));
g_print ("Crop view: %d×%d\n", gdk_pixbuf_get_width (crop), gdk_pixbuf_get_height (crop));

/* Modifying crop's pixels modifies original too (shared buffer) */
gdk_pixbuf_fill (crop, 0xFF0000FF); /* fill crop region red in the original */

g_object_unref (crop);
g_object_unref (copy);
g_object_unref (original);
```

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

### Async load pixbuf from stream

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Initiates a non-blocking load from a GInputStream. Call gdk_pixbuf_new_from_stream_finish inside the callback to retrieve the result. Ideal for event-loop based applications.

```c
static void
on_pixbuf_loaded (GObject *source, GAsyncResult *res, gpointer user_data)
{
    GError *error = NULL;
    GdkPixbuf *pixbuf = gdk_pixbuf_new_from_stream_finish (res, &error);

    if (pixbuf == NULL) {
        g_printerr ("Async load error: %s\n", error->message);
        g_error_free (error);
        return;
    }

    g_print ("Async loaded: %d×%d\n",
             gdk_pixbuf_get_width (pixbuf),
             gdk_pixbuf_get_height (pixbuf));
    g_object_unref (pixbuf);
}

/* In your setup code: */
gchar *raw_bytes;
gsize  raw_size;
g_file_get_contents ("image.jpg", &raw_bytes, &raw_size, NULL);

GInputStream *mem_stream = g_memory_input_stream_new_from_data (
    raw_bytes, raw_size, g_free);
gdk_pixbuf_new_from_stream_async (mem_stream, NULL, on_pixbuf_loaded, NULL);
g_object_unref (mem_stream);
```

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

### Load pixbuf from GResource

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads a pixbuf from a path inside a GResource bundle compiled into the application binary. Useful for shipping UI assets without separate files on disk.

```c
GError *error = NULL;

/* Resource path registered via glib-compile-resources */
GdkPixbuf *pixbuf = gdk_pixbuf_new_from_resource ("/com/example/app/logo.png", &error);
if (pixbuf == NULL) {
    g_error ("Failed to load resource: %s", error->message);
}

g_print ("Resource pixbuf: %d×%d\n",
         gdk_pixbuf_get_width (pixbuf),
         gdk_pixbuf_get_height (pixbuf));
g_object_unref (pixbuf);
```

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

### gdk_pixbuf_new_from_stream_async / gdk_pixbuf_new_from_stream_finish

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Initiates a non-blocking load from a GInputStream. The callback is invoked upon completion, and gdk_pixbuf_new_from_stream_finish should be called within the callback to retrieve the result. This is ideal for event-loop based applications.

```APIDOC
## gdk_pixbuf_new_from_stream_async / gdk_pixbuf_new_from_stream_finish

### Description
Initiates a non-blocking load from a `GInputStream`. When complete, `callback` is invoked; call `gdk_pixbuf_new_from_stream_finish` inside the callback to retrieve the result. Ideal for event-loop based applications (GTK, GLib main loop).

### Method Signature (Conceptual)
`gdk_pixbuf_new_from_stream_async(GInputStream *stream, GCancellable *cancellable, GAsyncReadyCallback callback, gpointer user_data)`
`gdk_pixbuf_new_from_stream_finish(GAsyncResult *res, GError **error)`

### Parameters
#### `gdk_pixbuf_new_from_stream_async`
- **stream** (GInputStream *) - The input stream to load the pixbuf from.
- **cancellable** (GCancellable *) - Optional. A `GCancellable` object that can be used to cancel the operation.
- **callback** (GAsyncReadyCallback) - The callback function to be called when the load is complete.
- **user_data** (gpointer) - User data to pass to the callback.

#### `gdk_pixbuf_new_from_stream_finish`
- **res** (GAsyncResult *) - The `GAsyncResult` passed to the callback.
- **error** (GError **) - If an error occurs, this will be set.

### Response
#### Success Response (`gdk_pixbuf_new_from_stream_finish`)
- **pixbuf** (GdkPixbuf *) - The loaded pixbuf.

### Example
```c
static void
on_pixbuf_loaded (GObject *source, GAsyncResult *res, gpointer user_data)
{
    GError *error = NULL;
    GdkPixbuf *pixbuf = gdk_pixbuf_new_from_stream_finish (res, &error);

    if (pixbuf == NULL) {
        g_printerr ("Async load error: %s\n", error->message);
        g_error_free (error);
        return;
    }

    g_print ("Async loaded: %d×%d\n",
             gdk_pixbuf_get_width (pixbuf),
             gdk_pixbuf_get_height (pixbuf));
    g_object_unref (pixbuf);
}

/* In your setup code: */
gchar *raw_bytes;
gsize  raw_size;
g_file_get_contents ("image.jpg", &raw_bytes, &raw_size, NULL);

GInputStream *mem_stream = g_memory_input_stream_new_from_data (
    raw_bytes, raw_size, g_free);
gdk_pixbuf_new_from_stream_async (mem_stream, NULL, on_pixbuf_loaded, NULL);
g_object_unref (mem_stream);
```
```

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

### gdk_pixbuf_new_from_file_at_size

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads an image scaled to fit inside a given bounding box while always preserving the original aspect ratio. This is equivalent to `gdk_pixbuf_new_from_file_at_scale` with `preserve_aspect_ratio` set to TRUE.

```APIDOC
## gdk_pixbuf_new_from_file_at_size

### Description
Loads an image scaled to fit inside the given `width` × `height` bounding box while always preserving the original aspect ratio. Equivalent to `gdk_pixbuf_new_from_file_at_scale` with `preserve_aspect_ratio = TRUE`.

### Method
`gdk_pixbuf_new_from_file_at_size`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the image file.

#### Other Parameters
- **width** (integer) - Required - The target width of the bounding box.
- **height** (integer) - Required - The target height of the bounding box.
- **error** (GError**) - Output parameter - Set on failure.

### Request Example
```c
GError *error = NULL;

/* Fit into a 128×128 icon slot */
GdkPixbuf *icon = gdk_pixbuf_new_from_file_at_size ("logo.svg", 128, 128, &error);
if (icon == NULL) {
    g_warning ("Could not load icon: %s", error->message);
    g_error_free (error);
} else {
    g_print ("Icon size: %d×%d\n",
             gdk_pixbuf_get_width (icon),
             gdk_pixbuf_get_height (icon));
    g_object_unref (icon);
}
```
```

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

### Clone GdkPixbuf Repository

Source: https://github.com/gnome/gdk-pixbuf/blob/master/CONTRIBUTING.md

Clone the GdkPixbuf Git repository and navigate into the project directory.

```sh
$ git clone https://gitlab.gnome.org/GNOME/gdk-pixbuf.git
$ cd gdk-pixbuf
```

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

### gdk_pixbuf_new_from_file_at_scale

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads an image from a file and scales it to fit within specified dimensions while preserving the aspect ratio if requested. This is useful for creating thumbnails or fitting images into constrained spaces.

```APIDOC
## gdk_pixbuf_new_from_file_at_scale

### Description
Loads an image from a file and scales it to fit within `width` × `height`. When `preserve_aspect_ratio` is `TRUE`, the image is scaled uniformly so that neither dimension exceeds the requested size; when `FALSE`, each axis is scaled independently to exactly the requested dimensions.

### Method
`gdk_pixbuf_new_from_file_at_scale`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the image file.

#### Other Parameters
- **width** (integer) - Required - The target width.
- **height** (integer) - Required - The target height.
- **preserve_aspect_ratio** (boolean) - Required - Whether to preserve the original aspect ratio.
- **error** (GError**) - Output parameter - Set on failure.

### Request Example
```c
GError *error = NULL;

/* Scale to at most 256×256, preserving aspect ratio */
GdkPixbuf *thumb = gdk_pixbuf_new_from_file_at_scale (
    "large-photo.jpg",
    256, 256,
    TRUE,   /* preserve_aspect_ratio */
    &error);

if (thumb == NULL) {
    g_printerr ("Error: %s\n", error->message);
    g_error_free (error);
} else {
    /* Actual dimensions will respect the original aspect ratio,
     * e.g. a 1600×900 source becomes 256×144 */
    g_print ("Thumbnail: %d×%d\n",
             gdk_pixbuf_get_width (thumb),
             gdk_pixbuf_get_height (thumb));
    g_object_unref (thumb);
}
```
```

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

### Create Typed GdkPixbuf Loaders

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Use `gdk_pixbuf_loader_new_with_type` or `gdk_pixbuf_loader_new_with_mime_type` to create loaders restricted to specific image formats for stricter validation. Handle potential errors during loader creation.

```c
GError *error = NULL;

/* Lock to PNG only */
GdkPixbufLoader *png_loader = gdk_pixbuf_loader_new_with_type ("png", &error);
if (png_loader == NULL) {
    g_printerr ("PNG loader unavailable: %s\n", error->message);
    g_error_free (error);
    return 1;
}

/* Or lock by MIME type */
GdkPixbufLoader *jpeg_loader = gdk_pixbuf_loader_new_with_mime_type ("image/jpeg", &error);
if (jpeg_loader == NULL) {
    g_printerr ("JPEG loader unavailable: %s\n", error->message);
    g_error_free (error);
}

gchar *data; gsize size;
g_file_get_contents ("image.png", &data, &size, NULL);
gdk_pixbuf_loader_write (png_loader, (guchar *) data, size, NULL);
gdk_pixbuf_loader_close (png_loader, NULL);

GdkPixbuf *pixbuf = gdk_pixbuf_loader_get_pixbuf (png_loader);
g_print ("PNG: %d×%d\n", gdk_pixbuf_get_width (pixbuf), gdk_pixbuf_get_height (pixbuf));

g_free (data);
g_object_unref (png_loader);
if (jpeg_loader) g_object_unref (jpeg_loader);
```

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

### Load Pixbuf from File

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Synchronously loads an image from a file path. Handles format detection and error reporting. Memory is managed with g_object_unref.

```c
#include <gdk-pixbuf/gdk-pixbuf.h>

int main (void)
{
    GError *error = NULL;
    GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file ("photo.png", &error);

    if (pixbuf == NULL) {
        g_printerr ("Failed to load image: %s\n", error->message);
        g_error_free (error);
        return 1;
    }

    g_print ("Loaded %d×%d image, %d channels, %s alpha\n",
             gdk_pixbuf_get_width (pixbuf),
             gdk_pixbuf_get_height (pixbuf),
             gdk_pixbuf_get_n_channels (pixbuf),
             gdk_pixbuf_get_has_alpha (pixbuf) ? "with" : "without");

    g_object_unref (pixbuf);
    return 0;
}
/* Expected output: Loaded 800×600 image, 3 channels, without alpha */
```

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

### Load Pixbuf from GInputStream

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads image data from any GIO GInputStream, supporting network connections, memory buffers, or other stream sources. Can be cancelled using GCancellable.

```c
#include <gio/gio.h>
#include <gdk-pixbuf/gdk-pixbuf.h>

GError *error = NULL;

/* Load from a file via GFile/GInputStream */
GFile *file = g_file_new_for_path ("image.png");
GInputStream *stream = (GInputStream *) g_file_read (file, NULL, &error);
g_assert_no_error (error);

GdkPixbuf *pixbuf = gdk_pixbuf_new_from_stream (stream, NULL /* cancellable */, &error);
if (pixbuf == NULL) {
    g_printerr ("Stream load failed: %s\n", error->message);
    g_error_free (error);
} else {
    g_print ("Loaded from stream: %d×%d\n",
             gdk_pixbuf_get_width (pixbuf),
             gdk_pixbuf_get_height (pixbuf));
    g_object_unref (pixbuf);
}

g_object_unref (stream);
g_object_unref (file);
```

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

### gdk_pixbuf_new_from_file

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Synchronously loads an image from a specified file path. The image format is auto-detected. Returns a new GdkPixbuf on success or NULL on failure.

```APIDOC
## gdk_pixbuf_new_from_file

### Description
Synchronously reads and decodes an image file at `filename`, auto-detecting the format from the file content. Returns a new `GdkPixbuf` on success, or `NULL` with `error` set on failure. Memory is managed with `g_object_unref`.

### Method
`gdk_pixbuf_new_from_file`

### Parameters
#### Path Parameters
- **filename** (string) - Required - The path to the image file.

#### Other Parameters
- **error** (GError**) - Output parameter - Set on failure.

### Request Example
```c
#include <gdk-pixbuf/gdk-pixbuf.h>

int main (void)
{
    GError *error = NULL;
    GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file ("photo.png", &error);

    if (pixbuf == NULL) {
        g_printerr ("Failed to load image: %s\n", error->message);
        g_error_free (error);
        return 1;
    }

    g_print ("Loaded %d×%d image, %d channels, %s alpha\n",
             gdk_pixbuf_get_width (pixbuf),
             gdk_pixbuf_get_height (pixbuf),
             gdk_pixbuf_get_n_channels (pixbuf),
             gdk_pixbuf_get_has_alpha (pixbuf) ? "with" : "without");

    g_object_unref (pixbuf);
    return 0;
}
/* Expected output: Loaded 800×600 image, 3 channels, without alpha */
```
```

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

### Incremental Image Loading with GdkPixbufLoader

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

The `GdkPixbufLoader` class allows for incremental decoding of image data fed chunk by chunk via `gdk_pixbuf_loader_write`. It emits signals as decoding progresses and the final pixbuf can be retrieved using `gdk_pixbuf_loader_get_pixbuf` after calling `gdk_pixbuf_loader_close`.

```c
#include <gdk-pixbuf/gdk-pixbuf.h>
#include <glib/gstdio.h>

static void
on_area_updated (
GdkPixbufLoader *loader,
                 gint x, gint y, gint width, gint height,
                 gpointer user_data)
{
    g_print ("  Area updated: (%d,%d) %d×%d\n", x, y, width, height);
}

int main (void)
{
    GError *error = NULL;

    /* Create loader — auto-detects format from data */
    GdkPixbufLoader *loader = gdk_pixbuf_loader_new ();

    /* Optionally request a specific decode size before writing data */
    gdk_pixbuf_loader_set_size (loader, 320, 240);

    g_signal_connect (loader, "area-updated", G_CALLBACK (on_area_updated), NULL);

    /* Simulate reading a file in 4 kB chunks */
    gchar *file_data;
    gsize  file_size;
    g_file_get_contents ("image.jpg", &file_data, &file_size, &error);
    g_assert_no_error (error);

    gsize  chunk_size = 4096;
    gsize  offset = 0;
    while (offset < file_size) {
        gsize to_write = MIN (chunk_size, file_size - offset);
        if (!gdk_pixbuf_loader_write (loader,
                                      (guchar *) file_data + offset,
                                      to_write,
                                      &error)) {
            g_printerr ("Write error: %s\n", error->message);
            g_error_free (error);
            break;
        }
        offset += to_write;
    }

    if (!gdk_pixbuf_loader_close (loader, &error)) {
        g_printerr ("Close error: %s\n", error->message);
        g_error_free (error);
    } else {
        GdkPixbuf *pixbuf = gdk_pixbuf_loader_get_pixbuf (loader);
        g_print ("Final pixbuf: %d×%d\n",
                 gdk_pixbuf_get_width (pixbuf),
                 gdk_pixbuf_get_height (pixbuf));
        /* pixbuf is owned by loader — do NOT unref it separately */
    }

    g_free (file_data);
    g_object_unref (loader);
    return 0;
}
```

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

### GdkPixbufSimpleAnim

Source: https://github.com/gnome/gdk-pixbuf/blob/master/docs/gdk-pixbuf-sections.txt

Functions for creating and managing simple GdkPixbufAnimation objects.

```APIDOC
## GdkPixbufSimpleAnim

### Description
Provides a simple way to create and manage animated images.

### Functions

- **gdk_pixbuf_simple_anim_new**
  - Creates a new GdkPixbufSimpleAnim with a default delay time.

- **gdk_pixbuf_simple_anim_add_frame**
  - Adds a frame to the animation.

- **gdk_pixbuf_simple_anim_set_loop**
  - Sets whether the animation should loop.

- **gdk_pixbuf_simple_anim_get_loop**
  - Gets whether the animation is set to loop.
```

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

### GdkPixbuf Module Interface

Source: https://github.com/gnome/gdk-pixbuf/blob/master/docs/gdk-pixbuf-sections.txt

Functions for initializing GdkPixbuf modules and querying image format information.

```APIDOC
## GdkPixbuf Module Interface

### Description
Manages the initialization of GdkPixbuf image loading modules and provides access to information about supported image formats.

### Functions

- **gdk_pixbuf_init_modules**
  - Initializes the GdkPixbuf module system.

- **gdk_pixbuf_get_formats**
  - Retrieves a list of supported GdkPixbuf formats.

### GdkPixbufFormat Functions

- **gdk_pixbuf_format_copy**
  - Creates a copy of a GdkPixbufFormat.

- **gdk_pixbuf_format_free**
  - Frees a GdkPixbufFormat.

- **gdk_pixbuf_format_get_name**
  - Gets the name of the format.

- **gdk_pixbuf_format_get_description**
  - Gets the description of the format.

- **gdk_pixbuf_format_get_mime_types**
  - Gets the MIME types associated with the format.

- **gdk_pixbuf_format_get_extensions**
  - Gets the file extensions associated with the format.

- **gdk_pixbuf_format_is_save_option_supported**
  - Checks if a save option is supported for the format.

- **gdk_pixbuf_format_is_writable**
  - Checks if the format can be written to.

- **gdk_pixbuf_format_is_scalable**
  - Checks if the format supports scaling.

- **gdk_pixbuf_format_is_disabled**
  - Checks if the format is disabled.

- **gdk_pixbuf_format_set_disabled**
  - Sets the disabled state of the format.

- **gdk_pixbuf_format_get_license**
  - Gets the license information for the format.
```

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

### Allocate new blank pixbuf

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Allocates a new zeroed pixel buffer. Always use GDK_COLORSPACE_RGB (the only supported colorspace), and 8 for bits_per_sample.

```c
/* Create a 640×480 RGB pixbuf without alpha channel */
GdkPixbuf *canvas = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, 640, 480);
g_assert_nonnull (canvas);

/* Fill the entire canvas with opaque red (RGBA packed as 0xRRGGBBxx) */
gdk_pixbuf_fill (canvas, 0xFF000000);

g_print ("Canvas: %d×%d, rowstride=%d, byte_length=%zu\n",
         gdk_pixbuf_get_width (canvas),
         gdk_pixbuf_get_height (canvas),
         gdk_pixbuf_get_rowstride (canvas),
         gdk_pixbuf_get_byte_length (canvas));
/* Expected: Canvas: 640×480, rowstride=1920, byte_length=921600 */

g_object_unref (canvas);
```

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

### gdk_pixbuf_new_from_resource

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads a pixbuf from a path within a GResource bundle compiled into the application binary. This is useful for including UI assets without requiring separate files.

```APIDOC
## gdk_pixbuf_new_from_resource

### Description
Loads a pixbuf from a path inside a GResource bundle compiled into the application binary. Useful for shipping UI assets without separate files on disk.

### Method Signature
`GdkPixbuf *gdk_pixbuf_new_from_resource(const char *path, GError **error)`

### Parameters
- **path** (const char *) - The resource path to load the pixbuf from (e.g., "/com/example/app/logo.png").
- **error** (GError **) - If an error occurs, this will be set.

### Response
#### Success Response
- **pixbuf** (GdkPixbuf *) - The pixbuf loaded from the resource.

### Example
```c
GError *error = NULL;

/* Resource path registered via glib-compile-resources */
GdkPixbuf *pixbuf = gdk_pixbuf_new_from_resource ("/com/example/app/logo.png", &error);
if (pixbuf == NULL) {
    g_error ("Failed to load resource: %s", error->message);
}

g_print ("Resource pixbuf: %d×%d\n",
         gdk_pixbuf_get_width (pixbuf),
         gdk_pixbuf_get_height (pixbuf));
g_object_unref (pixbuf);
```
```

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

### GdkPixbuf Utilities

Source: https://github.com/gnome/gdk-pixbuf/blob/master/docs/gdk-pixbuf-sections.txt

Utility functions for basic image manipulation.

```APIDOC
## GdkPixbuf Utilities

### Description
Offers a collection of utility functions for common image manipulation tasks.

### Functions

- **gdk_pixbuf_add_alpha**
  - Adds an alpha channel to a pixbuf.

- **gdk_pixbuf_copy_area**
  - Copies a rectangular area from one pixbuf to another.

- **gdk_pixbuf_saturate_and_pixelate**
  - Adjusts saturation and applies pixelation to a pixbuf.

- **gdk_pixbuf_apply_embedded_orientation**
  - Applies embedded orientation information to a pixbuf.

- **gdk_pixbuf_fill**
  - Fills a pixbuf with a specified color.
```

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

### Wrap GBytes object as pixbuf data

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Creates a GdkPixbuf backed by an immutable GBytes object. The pixbuf holds a reference to the GBytes, so the underlying memory stays alive as long as the pixbuf is alive.

```c
guchar raw[4 * 4 * 4];  /* 4×4 RGBA pixels */
memset (raw, 0xFF, sizeof (raw));   /* all white, fully opaque */

GBytes *bytes = g_bytes_new_static (raw, sizeof (raw));

GdkPixbuf *pixbuf = gdk_pixbuf_new_from_bytes (
    bytes,
    GDK_COLORSPACE_RGB,
    TRUE,   /* has_alpha */
    8,      /* bits_per_sample */
    4, 4,   /* width, height */
    4 * 4); /* rowstride */

/* Retrieve the backing GBytes */
GBytes *read_back = gdk_pixbuf_read_pixel_bytes (pixbuf);
g_assert (read_back == bytes);

g_bytes_unref (read_back);
g_bytes_unref (bytes);
g_object_unref (pixbuf);
```

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

### Handle Pixbuf Metadata Options

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Read, set, copy, and remove key/value metadata options from a pixbuf. PNG text chunk options are prefixed with "tEXt::".

```c
GError *error = NULL;
GdkPixbuf *pixbuf = gdk_pixbuf_new_from_file ("photo.jpg", &error);
g_assert_no_error (error);

/* Read EXIF orientation written by the JPEG loader */
const gchar *orient = gdk_pixbuf_get_option (pixbuf, "orientation");
if (orient)
    g_print ("EXIF orientation: %s\n", orient);

/* Set a custom option */
gdk_pixbuf_set_option (pixbuf, "tEXt::Software", "MyApp 1.0");

/* Copy all options to another pixbuf */
GdkPixbuf *copy = gdk_pixbuf_copy (pixbuf);
gdk_pixbuf_copy_options (pixbuf, copy);
g_print ("Software option on copy: %s\n",
         gdk_pixbuf_get_option (copy, "tEXt::Software"));

/* Remove an option */
gdk_pixbuf_remove_option (copy, "tEXt::Software");
g_assert_null (gdk_pixbuf_get_option (copy, "tEXt::Software"));

/* Enumerate all options */
GHashTable *opts = gdk_pixbuf_get_options (pixbuf);
GHashTableIter iter;
gpointer key, value;
g_hash_table_iter_init (&iter, opts);
while (g_hash_table_iter_next (&iter, &key, &value))
    g_print ("  option: %s = %s\n", (gchar *)key, (gchar *)value);

g_object_unref (copy);
g_object_unref (pixbuf);
```

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

### gdk_pixbuf_new

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Allocates a new, empty, zeroed pixel buffer. Always use GDK_COLORSPACE_RGB and 8 for bits_per_sample, as these are the only supported values.

```APIDOC
## gdk_pixbuf_new

### Description
Allocates a new zeroed pixel buffer. Always use `GDK_COLORSPACE_RGB` (the only supported colorspace), and 8 for `bits_per_sample`.

### Method Signature
`GdkPixbuf *gdk_pixbuf_new(GdkColorspace colorspace, gboolean has_alpha, int bits_per_sample, int width, int height)`

### Parameters
- **colorspace** (GdkColorspace) - The colorspace for the pixbuf. Must be `GDK_COLORSPACE_RGB`.
- **has_alpha** (gboolean) - `TRUE` if the pixbuf should have an alpha channel.
- **bits_per_sample** (int) - The number of bits per color sample. Must be 8.
- **width** (int) - The width of the pixbuf in pixels.
- **height** (int) - The height of the pixbuf in pixels.

### Response
#### Success Response
- **pixbuf** (GdkPixbuf *) - The newly allocated pixbuf.

### Example
```c
/* Create a 640×480 RGB pixbuf without alpha channel */
GdkPixbuf *canvas = gdk_pixbuf_new (GDK_COLORSPACE_RGB, FALSE, 8, 640, 480);
g_assert_nonnull (canvas);

/* Fill the entire canvas with opaque red (RGBA packed as 0xRRGGBBxx) */
gdk_pixbuf_fill (canvas, 0xFF000000);

g_print ("Canvas: %d×%d, rowstride=%d, byte_length=%zu\n",
         gdk_pixbuf_get_width (canvas),
         gdk_pixbuf_get_height (canvas),
         gdk_pixbuf_get_rowstride (canvas),
         gdk_pixbuf_get_byte_length (canvas));
/* Expected: Canvas: 640×480, rowstride=1920, byte_length=921600 */

g_object_unref (canvas);
```
```

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

### gdk_pixbuf_new_from_stream

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Loads image data from any GIO `GInputStream`, allowing loading from network connections, in-memory buffers, or other stream sources. An optional `GCancellable` can be provided to allow cancellation of the operation.

```APIDOC
## gdk_pixbuf_new_from_stream

### Description
Reads image data from any GIO `GInputStream`, enabling loading from network connections, in-memory buffers, or any other stream source. The optional `GCancellable` allows the operation to be cancelled.

### Method
`gdk_pixbuf_new_from_stream`

### Parameters
#### Other Parameters
- **stream** (GInputStream*) - Required - The input stream to read image data from.
- **cancellable** (GCancellable*) - Optional - A `GCancellable` object, or `NULL`.
- **error** (GError**) - Output parameter - Set on failure.

### Request Example
```c
#include <gio/gio.h>
#include <gdk-pixbuf/gdk-pixbuf.h>

GError *error = NULL;

/* Load from a file via GFile/GInputStream */
GFile *file = g_file_new_for_path ("image.png");
GInputStream *stream = (GInputStream *) g_file_read (file, NULL, &error);
g_assert_no_error (error);

GdkPixbuf *pixbuf = gdk_pixbuf_new_from_stream (stream, NULL /* cancellable */, &error);
if (pixbuf == NULL) {
    g_printerr ("Stream load failed: %s\n", error->message);
    g_error_free (error);
} else {
    g_print ("Loaded from stream: %d×%d\n",
             gdk_pixbuf_get_width (pixbuf),
             gdk_pixbuf_get_height (pixbuf));
    g_object_unref (pixbuf);
}

g_object_unref (stream);
g_object_unref (file);
```
```

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

### gdk_pixbuf_get_formats / gdk_pixbuf_get_file_info

Source: https://context7.com/gnome/gdk-pixbuf/llms.txt

Retrieves information about supported image formats and probes file headers to identify format and dimensions without full decoding. `gdk_pixbuf_get_formats` lists all available `GdkPixbufFormat` descriptors, while `gdk_pixbuf_get_file_info` identifies a file's format and dimensions from its header.

```APIDOC
## Format Discovery

### `gdk_pixbuf_get_formats` / `gdk_pixbuf_get_file_info` — Enumerate and probe formats

`gdk_pixbuf_get_formats` returns a list of all `GdkPixbufFormat` descriptors for installed loader modules. `gdk_pixbuf_get_file_info` probes a file's header bytes to identify its format and dimensions without fully decoding it.

```c
/* List all registered image formats */
GSList *formats = gdk_pixbuf_get_formats ();
for (GSList *l = formats; l != NULL; l = l->next) {
    GdkPixbufFormat *fmt = l->data;
    gchar  *name  = gdk_pixbuf_format_get_name (fmt);
    gchar  *desc  = gdk_pixbuf_format_get_description (fmt);
    gchar **exts  = gdk_pixbuf_format_get_extensions (fmt);
    gboolean writable = gdk_pixbuf_format_is_writable (fmt);

    g_print ("%-10s  %-30s  writable=%s  exts:", name, desc,
             writable ? "yes" : "no ");
    for (int i = 0; exts[i]; i++)
        g_print (" .%s", exts[i]);
    g_print ("\n");

    g_free (name); g_free (desc); g_strfreev (exts);
}
g_slist_free (formats);

/* Probe a file's format and dimensions without full decode */
gint probe_w = 0, probe_h = 0;
GdkPixbufFormat *fmt = gdk_pixbuf_get_file_info ("unknown.img", &probe_w, &probe_h);
if (fmt) {
    gchar *name = gdk_pixbuf_format_get_name (fmt);
    g_print ("Detected: %s, %d×%d\n", name, probe_w, probe_h);
    g_free (name);
} else {
    g_print ("Unknown image format\n");
}
```
```

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

### GdkPixbuf Scaling and Rotation

Source: https://github.com/gnome/gdk-pixbuf/blob/master/docs/gdk-pixbuf-sections.txt

Functions for scaling, rotating, and flipping images.

```APIDOC
## GdkPixbuf Scaling and Rotation

### Description
Provides functions for resizing, rotating, and flipping images with various interpolation methods.

### Functions

- **gdk_pixbuf_scale_simple**
  - Scales a pixbuf to a given width and height using a simple interpolation.

- **gdk_pixbuf_scale**
  - Scales a pixbuf to a given width and height using a specified interpolation type.

- **gdk_pixbuf_composite_color_simple**
  - Composites two pixbufs with a simple color transformation.

- **gdk_pixbuf_composite**
  - Composites two pixbufs with specified transformations.

- **gdk_pixbuf_composite_color**
  - Composites two pixbufs with a color transformation.

- **gdk_pixbuf_rotate_simple**
  - Rotates a pixbuf by 90, 180, or 270 degrees.

- **gdk_pixbuf_flip**
  - Flips a pixbuf horizontally or vertically.
```