ChafaFrame: Chafa Reference Manual

## ChafaFrame ChafaFrame — A raster image frame that can be added to a ChafaImage |

## Functions

ChafaFrame * | chafa_frame_new ()
ChafaFrame * | chafa_frame_new_borrow ()
ChafaFrame * | chafa_frame_new_steal ()
void | chafa_frame_ref ()
void | chafa_frame_unref ()

## Types and Values

typedef | ChafaFrame

## Description

A ChafaFrame contains the specific of a single frame of image data. It can be added to a ChafaImage.

## Functions

### chafa_frame_new ()

    ChafaFrame *
    chafa_frame_new (gconstpointer data,
                     ChafaPixelType pixel_type,
                     gint width,
                     gint height,
                     gint rowstride);

Creates a new ChafaFrame containing a copy of the image data pointed to by `data` .

#### Parameters

data | Pointer to an image data buffer to copy from |
pixel_type | The ChafaPixelType of the source data |
width | Width of the image, in pixels |
height | Height of the image, in pixels |
rowstride | Number of bytes to advance from the start of one row to the next |

#### Returns

The new frame

Since: 1.14

### chafa_frame_new_borrow ()

    ChafaFrame *
    chafa_frame_new_borrow (gpointer data,
                            ChafaPixelType pixel_type,
                            gint width,
                            gint height,
                            gint rowstride);

Creates a new ChafaFrame embedding the `data` pointer. It's the caller's responsibility to ensure the pointer remains valid for the lifetime of the frame. The frame will not free the buffer when its reference count drops to zero.

THIS IS DANGEROUS API which should only be used when the life cycle of the frame is short, stealing the buffer is impossible, and copying would cause unacceptable performance degradation.

Use `chafa_frame_new()` instead.

#### Parameters

data | Pointer to an image data buffer to assign |
pixel_type | The ChafaPixelType of the buffer |
width | Width of the image, in pixels |
height | Height of the image, in pixels |
rowstride | Number of bytes to advance from the start of one row to the next |

#### Returns

The new frame

Since: 1.14

### chafa_frame_new_steal ()

    ChafaFrame *
    chafa_frame_new_steal (gpointer data,
                           ChafaPixelType pixel_type,
                           gint width,
                           gint height,
                           gint rowstride);

Creates a new ChafaFrame, which takes ownership of the `data` buffer. The buffer will be freed with ``g_free()`` when the frame's reference count drops to zero.

#### Parameters

data | Pointer to an image data buffer to assign |
pixel_type | The ChafaPixelType of the buffer |
width | Width of the image, in pixels |
height | Height of the image, in pixels |
rowstride | Number of bytes to advance from the start of one row to the next |

#### Returns

The new frame

Since: 1.14

### chafa_frame_ref ()

    void
    chafa_frame_ref (ChafaFrame *frame);

Adds a reference to `frame` .

#### Parameters

frame | Frame to add a reference to |

Since: 1.14

### chafa_frame_unref ()

    void
    chafa_frame_unref (ChafaFrame *frame);

Removes a reference from `frame` . When the reference count drops to zero, the frame is freed and can no longer be used.

#### Parameters

frame | Frame to remove a reference from |

Since: 1.14

## Types and Values

### ChafaFrame

    typedef struct ChafaFrame ChafaFrame;