asc-image: AppStream Compose Library Reference Manual

## asc-image

asc-image — Basic image rendering functions.

## Functions

GQuark | asc_image_error_quark ()
const gchar * | asc_image_format_to_string ()
AscImageFormat | asc_image_format_from_string ()
AscImageFormat | asc_image_format_from_filename ()
gboolean | asc_optimize_png ()
GHashTable * | asc_image_supported_format_names ()
AscImage * | asc_image_new ()
AscImage * | asc_image_new_from_file ()
AscImage * | asc_image_new_from_data ()
gboolean | asc_image_load_filename ()
GdkPixbuf * | asc_image_save_pixbuf ()
gboolean | asc_image_save_filename ()
GdkPixbuf * | asc_image_get_pixbuf ()
void | asc_image_set_pixbuf ()
guint | asc_image_get_width ()
guint | asc_image_get_height ()
void | asc_image_scale ()
void | asc_image_scale_to_width ()
void | asc_image_scale_to_height ()
void | asc_image_scale_to_fit ()
void | asc_pixbuf_blur ()
void | asc_pixbuf_sharpen ()

## Types and Values

#define | ASC_TYPE_IMAGE
enum | AscImageSaveFlags
enum | AscImageLoadFlags
enum | AscImageFormat
enum | AscImageError
#define | ASC_IMAGE_ERROR
| AscImage

## Includes

    #include <appstream-compose.h>

## Description

## Functions

### asc_image_error_quark ()

    GQuark
    asc_image_error_quark (void);

#### Returns

An error quark.

### asc_image_format_to_string ()

    const gchar *
    asc_image_format_to_string (AscImageFormat format);

Converts the enumerated value to an text representation.

#### Parameters

format | the `AscImageFormat`. |

#### Returns

string version of `format`

### asc_image_format_from_string ()

    AscImageFormat
    asc_image_format_from_string (const gchar *str);

Converts the text representation to an enumerated value.

#### Parameters

str | the string. |

#### Returns

a AscImageFormat or `ASC_IMAGE_FORMAT_UNKNOWN` for unknown

### asc_image_format_from_filename ()

    AscImageFormat
    asc_image_format_from_filename (const gchar *fname);

Returns the image format type based on the given file's filename.

#### Parameters

fname | the filename. |

#### Returns

a AscImageFormat or `ASC_IMAGE_FORMAT_UNKNOWN` for unknown

### asc_optimize_png ()

    gboolean
    asc_optimize_png (const gchar *fname,
                      GError **error);

Optimizes a PNG graphic for size with optipng, if its binary is available and this feature is enabled.

#### Parameters

fname | Filename of the PNG image to optimize. |
error | A GError or `NULL` |

### asc_image_supported_format_names ()

    GHashTable *
    asc_image_supported_format_names (void);

Get a set of image format names we can currently read (via GdkPixbuf).

#### Returns

A hash set of format names.

[transfer full]

### asc_image_new ()

    AscImage *
    asc_image_new (void);

Creates a new AscImage.

### asc_image_new_from_file ()

    AscImage *
    asc_image_new_from_file (const gchar *fname,
                             guint dest_size,
                             AscImageLoadFlags flags,
                             GError **error);

Creates a new AscImage from a file on the filesystem.

#### Parameters

fname | Name of the file to load. |
dest_size | The size of the constructed pixbuf, or 0 for the native size |
flags | a AscImageLoadFlags, e.g. `ASC_IMAGE_LOAD_FLAG_NONE` |
error | A GError or `NULL` |

### asc_image_new_from_data ()

    AscImage *
    asc_image_new_from_data (const void *data,
                             gssize len,
                             guint dest_size,
                             gboolean compressed,
                             AscImageLoadFlags flags,
                             GError **error);

Creates a new AscImage from data in memory.

#### Parameters

data | Data to load. |
len | Length of the data to load. |
dest_size | The size of the constructed pixbuf, or 0 for the native size |
flags | a AscImageLoadFlags, e.g. `ASC_IMAGE_LOAD_FLAG_NONE` |
compressed | `TRUE` if passed data is gzip-compressed |
error | A GError or `NULL` |

### asc_image_load_filename ()

    gboolean
    asc_image_load_filename (AscImage *image,
                             const gchar *filename,
                             guint dest_size,
                             guint src_size_min,
                             AscImageLoadFlags flags,
                             GError **error);

Reads an image from a file.

#### Parameters

image | a AscImage instance. |
filename | filename to read from |
dest_size | The size of the constructed pixbuf, or 0 for the native size |
src_size_min | The smallest source size allowed, or 0 for none |
flags | a AscImageLoadFlags, e.g. `ASC_IMAGE_LOAD_FLAG_NONE` |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

### asc_image_save_pixbuf ()

    GdkPixbuf *
    asc_image_save_pixbuf (AscImage *image,
                           guint width,
                           guint height,
                           AscImageSaveFlags flags);

Resamples a pixbuf to a specific size.

#### Parameters

image | a AscImage instance. |
width | target width, or 0 for default |
height | target height, or 0 for default |
flags | some AscImageSaveFlags values, e.g. `ASC_IMAGE_SAVE_FLAG_PAD_16_9` |

#### Returns

A GdkPixbuf of the specified size.

[transfer full]

### asc_image_save_filename ()

    gboolean
    asc_image_save_filename (AscImage *image,
                             const gchar *filename,
                             guint width,
                             guint height,
                             AscImageSaveFlags flags,
                             GError **error);

Saves the image to a file.

#### Parameters

image | a AscImage instance. |
filename | filename to write to |
width | target width, or 0 for default |
height | target height, or 0 for default |
flags | some AscImageSaveFlags values, e.g. `ASC_IMAGE_SAVE_FLAG_PAD_16_9` |
error | A GError or `NULL`. |

#### Returns

`TRUE` for success

### asc_image_get_pixbuf ()

    GdkPixbuf *
    asc_image_get_pixbuf (AscImage *image);

Gets the image pixbuf if set.

#### Parameters

image | a AscImage instance. |

#### Returns

the GdkPixbuf, or `NULL`.

[transfer none]

### asc_image_set_pixbuf ()

    void
    asc_image_set_pixbuf (AscImage *image,
                          GdkPixbuf *pixbuf);

Sets the image pixbuf.

#### Parameters

image | a AscImage instance. |
pixbuf | the GdkPixbuf, or `NULL` |

### asc_image_get_width ()

    guint
    asc_image_get_width (AscImage *image);

Gets the image width.

#### Parameters

image | an AscImage instance. |

### asc_image_get_height ()

    guint
    asc_image_get_height (AscImage *image);

Gets the image height.

#### Parameters

image | an AscImage instance. |

### asc_image_scale ()

    void
    asc_image_scale (AscImage *image,
                     guint new_width,
                     guint new_height);

Scale the image to the given size.

#### Parameters

image | an AscImage instance. |
new_width | The new width. |
new_height | the new height. |

### asc_image_scale_to_width ()

    void
    asc_image_scale_to_width (AscImage *image,
                              guint new_width);

Scale the image to the given width, preserving its aspect ratio.

#### Parameters

image | an AscImage instance. |
new_width | The new width. |

### asc_image_scale_to_height ()

    void
    asc_image_scale_to_height (AscImage *image,
                               guint new_height);

Scale the image to the given height, preserving its aspect ratio.

#### Parameters

image | an AscImage instance. |
new_height | the new height. |

### asc_image_scale_to_fit ()

    void
    asc_image_scale_to_fit (AscImage *image,
                            guint size);

Scale the image to fir in a square with the given edge length, and keep its aspect ratio.

#### Parameters

image | an AscImage instance. |
size | the maximum edge length. |

### asc_pixbuf_blur ()

    void
    asc_pixbuf_blur (GdkPixbuf *src,
                     gint radius,
                     gint iterations);

### asc_pixbuf_sharpen ()

    void
    asc_pixbuf_sharpen (GdkPixbuf *src,
                        gint radius,
                        gdouble amount);

## Types and Values

### ASC_TYPE_IMAGE

    #define ASC_TYPE_IMAGE (asc_image_get_type ())

### enum AscImageSaveFlags

The flags used for saving images.

#### Members

ASC_IMAGE_SAVE_FLAG_NONE | No special flags set |
ASC_IMAGE_SAVE_FLAG_OPTIMIZE | Optimize generated PNG for size |
ASC_IMAGE_SAVE_FLAG_PAD_16_9 | Pad with alpha to 16:9 aspect |
ASC_IMAGE_SAVE_FLAG_SHARPEN | Sharpen the image to clarify detail |
ASC_IMAGE_SAVE_FLAG_BLUR | Blur the image to clear detail |

### enum AscImageLoadFlags

The flags used for loading images.

#### Members

ASC_IMAGE_LOAD_FLAG_NONE | No special flags set |
ASC_IMAGE_LOAD_FLAG_SHARPEN | Sharpen the resulting image |
ASC_IMAGE_LOAD_FLAG_ALLOW_UNSUPPORTED | Allow loading of unsupported image types. |
ASC_IMAGE_LOAD_FLAG_ALWAYS_RESIZE | Always resize the source image to the perfect size |

### enum AscImageFormat

File format of an image.

#### Members

ASC_IMAGE_FORMAT_UNKNOWN | Unknown image format. |
ASC_IMAGE_FORMAT_PNG | PNG format |
ASC_IMAGE_FORMAT_JPEG | JPEG format |
ASC_IMAGE_FORMAT_GIF | GIF format |
ASC_IMAGE_FORMAT_SVG | SVG format |
ASC_IMAGE_FORMAT_SVGZ | Compressed SVG format |
ASC_IMAGE_FORMAT_WEBP | WebP format |
ASC_IMAGE_FORMAT_AVIF | AVIF format |
ASC_IMAGE_FORMAT_XPM | XPM format |

### enum AscImageError

An image processing error.

#### Members

ASC_IMAGE_ERROR_FAILED | Generic failure. |
ASC_IMAGE_ERROR_UNSUPPORTED | The graphic type is not supported. |

### ASC_IMAGE_ERROR

    #define ASC_IMAGE_ERROR asc_image_error_quark ()

### AscImage

    typedef struct _AscImage AscImage;