Caution: 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 <graphics/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).
palette
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 allocated, and the unshaded portions represent the memory area that's actually usable for the surface.


Note: 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, for example, for textures.
DISP_SURFACE_VMI_TARGETABLE
Video capture hardware can write frames into this surface.
DISP_SURFACE_PAGE_ALIGNED
Surface memory starts on a page boundary.
DISP_SURFACE_BYTES_REVERSED
Surface memory accesses by CPU are byte-swapped. Only valid for 16 and 32bpp surfaces. See the section on Pixel formats in the Writing a Graphics Driver chapter.
DISP_SURFACE_NON_CACHEABLE
The CPU shouldn't map the surface memory as cacheable.
DISP_SURFACE_PHYS_CONTIG
The surface memory is physically contiguous.
DISP_SURFACE_DRIVER_NOT_OWNER
The surface wasn't created by your device driver
DISP_SURFACE_ALPHA_MAP
The surface can be used as an alpha map for a blending operation.

Classification:

Neutrino

See also:

disp_adapter_t, disp_draw_context_t, disp_draw_contextfuncs_t, disp_draw_corefuncs_t, disp_draw_miscfuncs_t, disp_memfuncs_t, disp_modefuncs_t, disp_vcapfuncs_t