gf_surface_attach()

Create a new surface from existing memory

Synopsis:

#include <gf/gf.h>

int gf_surface_attach( gf_surface_t* psurface,
                       gf_dev_t gdev,
                       int w,
                       int h,
                       int stride,
                       gf_format_t format,
                       const gf_palette_t* palette,
                       uint8_t* ptr,
                       unsigned flags );

Arguments:

psurface

The address where the function can store a handle for the surface.

gdev

The graphics context that's responsible for managing the surface, returned by gf_dev_attach().

w, h

The width and height of the surface, in pixels.

stride

Number of bytes per scanline.

format

The gf_format_t display format of the surface. If you are using a packed format, you must pass a format that has an explicit endianness, rather than the non-endian-specific variant.

palette

A pointer to a gf_palette_t structure, which represents the surface palette. You may pass NULL only if the surface format is not palette-based (GF_FORMAT_PAL8).

ptr

A pointer to the memory buffer containing image data.

flags

Flags affecting the surface properties. None are currently defined; pass 0.

Library:

gf

Description:

This function creates a new surface and attaches it to an existing area of memory. This wraps your own area of memory (or preexisting frame data, such as a previously loaded image) in a format that can be manipulated by the GF API as a regular surface (with some restrictions).

Because the driver knows nothing about the nature of the memory or how it was allocated, the hardware renderer can't target attached surfaces directly. Any rendering or blitting to or from the surface is done in software.

For the same reason, the application is responsible for deallocating the memory containing the frame data. This should be done only after all attached surfaces are done with the memory (that is, after all attached surfaces have been deallocated with gf_surface_free()).

Memory can't be shared because io-display doesn't manage it. Therefore, other processes aren't able to access attached surfaces via gf_surface_attach_by_sid().

Returns:

GF_ERR_OK

Success.

GF_GF_ERR_MEM

Memory allocation failure.

GF_ERR_PARM

Unable to satisfy the criteria; verify that the pixel format meets the requirements set out by the flags for the given hardware.

Classification:

QNX Graphics Framework

See also:

gf_palette_t, gf_surface_create(), gf_surface_create_layer(), gf_surface_free(), gf_surface_reattach()