gf_surface_get_info()

Get surface parameters

Synopsis:

#include <gf/gf.h>

gf_surface_info_t *gf_surface_get_info(
        gf_surface_t surface,
        gf_surface_info_t *info);

Arguments:

surface

The handle for the surface.

info

The address of a structure that the function can fill with surface information (see below). Do not pass NULL.

Library:

gf

Description:

This function retrieves surface parameters.

---

If the surface ID (SID) is reported as GF_SID_INVALID by this function, then the surface isn't being managed by io-display and therefore can't be shared across process boundaries.

---

The info parameter contains information about the surface:

typedef struct {
    gf_sid_t            sid;
    int                 w;
    int                 h;
    gf_format_t         format;
    unsigned            stride;
    _uint64             paddr;
    _uint8*             vaddr;
    gf_palette_t        palette;
    unsigned            flags;
} gf_surface_info_t;

It contains at least these parameters:

sid

If this surface was allocated by io-display, this field specifies the numerical identifier that is assigned to this surface, which is guaranteed to be unique across the entire device. If the surface was not allocated by io-display (as in the case of gf_surface_attach(), this field is set to a value of GF_SID_INVALID.

w, h

The width and height of the surface, in pixels.

format

The pixel format of the surface. See gf_format_t for a list of possible pixel formats.

---

The format filled in by gf_surface_get_info() will be endian-specific.

---

stride

The number of bytes per scanline.

paddr

The physical address of the surface memory buffer. You should use this only if the flags member has the GF_SURFACE_PHYS_CONTIG flag bit set.

vaddr

Virtual address of the surface memory buffer. You should use this only if the surface was created with the GF_SURFACE_CREATE_CPU_LINEAR_ACCESSIBLE flag bit set.

palette

The surface palette, of type gf_palette_t. This member is valid only if the surface format is GF_FORMAT_PAL8.

flags

Flags that provide additional information regarding the surface. Valid bits include:

GF_SURFACE_DISPLAYABLE

The surface can be displayed via a CRT controller.

GF_SURFACE_CPU_LINEAR_READABLE

The CPU can read this surface directly.

GF_SURFACE_CPU_LINEAR_WRITEABLE

The CPU can write to this surface directly.

GF_SURFACE_2D_READABLE

The surface is read-accessible by the 2D engine.

GF_SURFACE_3D_READABLE

The surface is read-accessible by the 3D engine.

GF_SURFACE_2D_TARGETABLE

The 2D engine can render into the surface.

GF_SURFACE_3D_TARGETABLE

The 3D engine can render into the surface.

GF_SURFACE_ALPHA_MAP

The Surface can be used as the alpha map source for 2D rendering

GF_SURFACE_SCALER_DISPLAYABLE

The surface can be displayed via a video overlay scaler.

GF_SURFACE_VMI_TARGETABLE

Video in hardware can write frames into the surface.

GF_SURFACE_DMA_SAFE

The DMA engine can treat the surface memory as one contiguous block.

GF_SURFACE_PAGE_ALIGNED

The surface memory starts on a page boundary, and its linear size is a multiple of the page size.

GF_SURFACE_BYTES_REVERSED

The byte order is reversed. This is valid only for 16- and 32-bpp surfaces.

GF_SURFACE_NON_CACHEABLE

The memory should be mapped noncacheable.

GF_SURFACE_WT_CACHEABLE

The memory can be mapped write-through cacheable (but not write-back cacheable).

GF_SURFACE_PHYS_CONTIG

The memory is physically contiguous.

GF_SURFACE_DRIVER_NOT_OWNER

The driver did not create or allocate this surface.

---

In most cases, there is a one-for-one mapping between the GF_SURFACE_CREATE_xxxx flags that are passed to gf_surface_create() and gf_surface_create_layer() and the GF_SURFACE_xxxx flags which populate the gf_surface_info_t.flags member. These creation flags result in the following: GF_SURFACE_CREATE_2D_ACCESSIBLE On success, will cause either the GF_SURFACE_2D_READABLE and/or the GF_SURFACE_2D_TARGETABLE bit(s) to be set. GF_SURFACE_CREATE_3D_ACCESSIBLE On success, will case either the GF_SURFACE_3D_READABLE and or the GF_SURFACE_3D_TARGETABLE bits to be set. Any remaining flags which are returned in the gf_surface_info_t.flags member, and do not have a corresponding creation flag, are used for additional feedback requirements only. Any further attempts to create mappings will result in vague understandings being propagated.

---

Returns:

The address passed in.

Classification:

QNX Graphics Framework

See also:

gf_format_t, gf_palette_t, gf_surface_attach(), gf_surface_create(), gf_surface_create_layer()