Miscellaneous: Chafa Reference Manual

## Miscellaneous Miscellaneous — Potentially useful functions |

## Functions

void | chafa_calc_canvas_geometry ()
void | chafa_free_gstring_array ()

## Types and Values

#define | CHAFA_MAJOR_VERSION
#define | CHAFA_MICRO_VERSION
#define | CHAFA_MINOR_VERSION
#define | CHAFA_VERSION_MIN_REQUIRED
#define | CHAFA_VERSION_MAX_ALLOWED
#define | CHAFA_VERSION_CUR_STABLE
#define | CHAFA_VERSION_PREV_STABLE
#define | CHAFA_VERSION_1_0
#define | CHAFA_VERSION_1_2
#define | CHAFA_VERSION_1_4
#define | CHAFA_VERSION_1_6
#define | CHAFA_VERSION_1_8
#define | CHAFA_VERSION_1_10
#define | CHAFA_VERSION_1_12
#define | CHAFA_VERSION_1_14
#define | CHAFA_VERSION_1_16
#define | CHAFA_VERSION_1_18
enum | ChafaPixelType

## Description

Miscellaneous functions that may be useful to Chafa users.

## Functions

### chafa_calc_canvas_geometry ()

    void
    chafa_calc_canvas_geometry (gint src_width,
                                gint src_height,
                                gint *dest_width_inout,
                                gint *dest_height_inout,
                                gfloat font_ratio,
                                gboolean zoom,
                                gboolean stretch);

Calculates an optimal geometry for a ChafaCanvas given the width and height of an input image, maximum width and height of the canvas, font ratio, zoom and stretch preferences.

`src_width` and `src_height` must both be zero or greater.

`dest_width_inout` and `dest_height_inout` must point to integers containing the maximum dimensions of the canvas in character cells. These will be replaced by the calculated values, which may be zero if one of the input dimensions is zero. If one or both of the input parameters is negative, they will be treated as unspecified and calculated based on the remaining parameters and aspect ratio.

`font_ratio` is the font's width divided by its height. 0.5 is a typical value.

#### Parameters

src_width | Width of source |
src_height | Height of source |
dest_width_inout | Inout location for width of destination |
dest_height_inout | Inout location for height of destination |
font_ratio | Target font's width to height ratio |
zoom | `TRUE` to upscale image to fit maximum dimensions, `FALSE` otherwise |
stretch | `TRUE` to ignore aspect of source, `FALSE` otherwise |

### chafa_free_gstring_array ()

    void
    chafa_free_gstring_array (GString **gsa);

Frees an array of GString. If `gsa` is `NULL`, simply returns without doing anything.

#### Parameters

gsa | Pointer to a `NULL`-terminated array of pointers to GString |

## Types and Values

### CHAFA_MAJOR_VERSION

    #define CHAFA_MAJOR_VERSION 1

### CHAFA_MICRO_VERSION

    #define CHAFA_MICRO_VERSION 2

### CHAFA_MINOR_VERSION

    #define CHAFA_MINOR_VERSION 18

### CHAFA_VERSION_MIN_REQUIRED

    # define CHAFA_VERSION_MIN_REQUIRED      (CHAFA_VERSION_1_0)

A macro that can be defined by the user prior to including the chafa.h header. The definition should be one of the predefined Chafa version macros: `CHAFA_VERSION_1_0`, `CHAFA_VERSION_1_2`,...

This macro defines the earliest version of Chafa that the package is required to be able to compile against.

If the compiler is configured to warn about the use of deprecated functions, then using functions that were deprecated in version `CHAFA_VERSION_MIN_REQUIRED` or earlier will cause warnings (but using functions deprecated in later releases will not).

Since: 1.2

### CHAFA_VERSION_MAX_ALLOWED

    # define CHAFA_VERSION_MAX_ALLOWED      (CHAFA_VERSION_CUR_STABLE)

A macro that can be defined by the user prior to including the chafa.h header. The definition should be one of the predefined Chafa version macros: `CHAFA_VERSION_1_0`, `CHAFA_VERSION_1_2`,...

This macro defines the latest version of the Chafa API that the package is allowed to make use of.

If the compiler is configured to warn about the use of deprecated functions, then using functions added after version `CHAFA_VERSION_MAX_ALLOWED` will cause warnings.

This should normally be set to the same value as `CHAFA_VERSION_MIN_REQUIRED`.

Since: 1.2

### CHAFA_VERSION_CUR_STABLE

    #define CHAFA_VERSION_CUR_STABLE         (G_ENCODE_VERSION (CHAFA_MAJOR_VERSION, CHAFA_MINOR_VERSION + 1))

### CHAFA_VERSION_PREV_STABLE

    #define CHAFA_VERSION_PREV_STABLE        (G_ENCODE_VERSION (CHAFA_MAJOR_VERSION, CHAFA_MINOR_VERSION - 1))

### CHAFA_VERSION_1_0

    #define CHAFA_VERSION_1_0 (G_ENCODE_VERSION (1, 0))

### CHAFA_VERSION_1_2

    #define CHAFA_VERSION_1_2 (G_ENCODE_VERSION (1, 2))

### CHAFA_VERSION_1_4

    #define CHAFA_VERSION_1_4 (G_ENCODE_VERSION (1, 4))

### CHAFA_VERSION_1_6

    #define CHAFA_VERSION_1_6 (G_ENCODE_VERSION (1, 6))

### CHAFA_VERSION_1_8

    #define CHAFA_VERSION_1_8 (G_ENCODE_VERSION (1, 8))

### CHAFA_VERSION_1_10

    #define CHAFA_VERSION_1_10 (G_ENCODE_VERSION (1, 10))

### CHAFA_VERSION_1_12

    #define CHAFA_VERSION_1_12 (G_ENCODE_VERSION (1, 12))

### CHAFA_VERSION_1_14

    #define CHAFA_VERSION_1_14 (G_ENCODE_VERSION (1, 14))

### CHAFA_VERSION_1_16

    #define CHAFA_VERSION_1_16 (G_ENCODE_VERSION (1, 16))

### CHAFA_VERSION_1_18

    #define CHAFA_VERSION_1_18 (G_ENCODE_VERSION (1, 18))

### enum ChafaPixelType

Pixel formats supported by ChafaCanvas and ChafaSymbolMap.

#### Members

CHAFA_PIXEL_RGBA8_PREMULTIPLIED | Premultiplied RGBA, 8 bits per channel. |
CHAFA_PIXEL_BGRA8_PREMULTIPLIED | Premultiplied BGRA, 8 bits per channel. |
CHAFA_PIXEL_ARGB8_PREMULTIPLIED | Premultiplied ARGB, 8 bits per channel. |
CHAFA_PIXEL_ABGR8_PREMULTIPLIED | Premultiplied ABGR, 8 bits per channel. |
CHAFA_PIXEL_RGBA8_UNASSOCIATED | Unassociated RGBA, 8 bits per channel. |
CHAFA_PIXEL_BGRA8_UNASSOCIATED | Unassociated BGRA, 8 bits per channel. |
CHAFA_PIXEL_ARGB8_UNASSOCIATED | Unassociated ARGB, 8 bits per channel. |
CHAFA_PIXEL_ABGR8_UNASSOCIATED | Unassociated ABGR, 8 bits per channel. |
CHAFA_PIXEL_RGB8 | Packed RGB (no alpha), 8 bits per channel. |
CHAFA_PIXEL_BGR8 | Packed BGR (no alpha), 8 bits per channel. |
CHAFA_PIXEL_MAX | Last supported pixel type, plus one. |

Since: 1.4