This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

`disp_surface_t`

Description of a two-dimensional surface

Synopsis:

#include <display.h>

typedef struct disp_surface {
    int             size;
    unsigned        pixel_format;
    unsigned        offset;
    unsigned char   *vidptr;
    uintptr_t       paddr;
    unsigned        stride;
    unsigned        flags;
    int             width;
    int             height;
    disp_color_t    *palette;
    int             palette_valid_entries;
    disp_adapter_t  *adapter;
    unsigned        reserved;
} disp_surface_t;

Description:

The disp_surface_t structure describes a two-dimensional surface. It's used as an argument to several functions, and is also used within other structures, such as disp_draw_context_t.

The members include:

size: The size of this structure. Any time a driver creates a structure of this type, it should set this member to sizeof (disp_surface_t).
pixel_format: The pixel format. For more information, see "Pixel formats" in the Writing a Graphics Driver chapter.
offset: A device-dependent address that points to the start of the surface data.
vidptr: The virtual (CPU) address that points to the start of the surface data.
paddr: The physical (bus) address that points to the start of the surface data.
stride: The number of bytes from the beginning of one scanline to the beginning of the next (see diagram below).
flags: Surface flags, defined below.
width: The width of the surface, in pixels (see diagram below).
height: The height of the surface, in scan lines (see diagram below).
pal_ptr: A pointer to the palette for this surface. If not a palette type, this pointer is NULL.
pal_valid_entries: The number of entries that are valid in the pal_ptr palette. For palette-based surface data, pixel values in the data shouldn't exceed this value, otherwise they might reference past the end of the palette array.
adapter: A pointer to the disp_adapter_t structure for the device that created this surface (if any).

Relationship of stride, height, and width

The three members, stride, height, and width are used to define a surface as follows:

Memory layout.

Memory layout.

The entire content of the box represents the total memory area available, and the unshaded portions represent the memory area that's actually used for the surface.

Don't overwrite the "not used" areas; it might be used to store other surfaces.

flags

The flags member is a bitmap of the following values:

DISP_SURFACE_DISPLAYABLE: The surface can be displayed via CRT controller.
DISP_SURFACE_CPU_LINEAR_READABLE: The CPU can read this surface directly.
DISP_SURFACE_CPU_LINEAR_WRITEABLE: The CPU can write to this surface directly.
DISP_SURFACE_2D_TARGETABLE: The 2D engine can render into this surface.
DISP_SURFACE_2D_READABLE: The surface is read-accessible by 2D engine.
DISP_SURFACE_3D_TARGETABLE: The 3D engine can render into surface.
DISP_SURFACE_3D_READABLE: The surface is read-accessible by 3D engine.
DISP_SURFACE_SCALER_DISPLAYABLE: The surface can be displayed via video overlay scaler.
DISP_SURFACE_VMI_TARGETABLE: Video capture hardware can write frames into this surface.
DISP_SURFACE_DMA_SAFE: The DMA engine can treat the surface memory as one contiguous block.
DISP_SURFACE_PAGE_ALIGNED: Surface memory starts on a page boundary.
DISP_SURFACE_OTHER_ENDIAN: Surface memory accesses by CPU are byte-swapped; the device on which the memory resides in the opposite "endian" from the CPU.
DISP_SURFACE_NON_CACHEABLE: The CPU shouldn't map the surface memory as cacheable.
DISP_SURFACE_PHYS_CONTIG: The surface memory is physically contiguous, from a bus master device's perspective.

Classification:

Photon