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.

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.

---

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