[Previous] [Contents] [Index] [Next]
Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

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.

Note: 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.
Note: 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.
Note: 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

Safety:
Interrupt handler No
Signal handler No
Thread Yes

See also:

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

[Previous] [Contents] [Index] [Next]