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

`disp_memfuncs_t`

Table of memory management functions

Synopsis:

#include <vmem.h>

typedef struct disp_memfuncs {
    int  (*init) (...);
    void (*fini) (...);
    void (*module_info) (...);
    int  (*reset) (...);
    int  (*alloc_surface) (...);
    int  (*alloc_layer_surface) (...);
    int  (*free_surface) (...);
    int  (*mem_avail) (...);
} disp_memfuncs_t;

The disp_memfuncs_t structure is a table that your driver uses to define the memory management functions that it provides to the graphics framework. Your driver's devg_get_memfuncs() entry point must fill in this structure.

init()

The graphics framework calls this function to initialize the memory manager. The prototype is:

int (*init) (disp_adapter_t *adapter,
             char *optstring)

The graphics framework calls this function before any of the other functions in the disp_memfuncs_t structure. For more information on where this function fits into the general flow, see "Calling sequence" in the Writing a Graphics Driver chapter.

fini()

The graphics framework calls this function to shut down the memory management module, freeing any resources that it allocated. The prototype is:

int (*fini) (disp_adapter_t *adapter)

For more information on where this function fits into the general flow, see "Calling sequence" in the Writing a Graphics Driver chapter.

module_info()

The prototype is:

int (*module_info) (disp_adapter_t *adapter,
                    disp_module_info_t *info)

This function must fill in the disp_module_info_t structure pointed to by module_info.

reset()

The graphics framework calls this function to reset the memory management module to its initial state. The prototype is:

int (*reset) (
        disp_adapter_t *adapter,
        disp_surface_t *surf )

alloc_surface()

The graphics framework calls this function to allocate video memory to contain a 2D surface. The prototype is:

disp_surface_t * (*alloc_surface) (
                     disp_adapter_t *adapter,
                     int width,
                     int height,
                     unsigned format,
                     unsigned flags,
                     unsigned user_flags)

The size of the surface is width pixels by height scanlines. This function must allocate a disp_surface_t structure and initialize it to describe the allocated surface memory. Set the structure's adapter member to point to the driver's disp_adapter_t structure.

If there isn't enough video RAM, your driver can allocate the surface from system RAM, but when the driver works with surfaces, it must use the flags defined for disp_surface_t to determine where the surfaces are defined. The driver must also be able to work with surfaces that aren't all in video RAM.

The function must return a pointer to the allocated disp_surface_t and must ensure that the memory it allocates conforms to the surface properties requested by the flags parameter. This implies that when the function returns, any flags set in flags are also set in the flags member of the returned surface.

There are currently no user flags defined; your driver should ignore the user_flags argument.

alloc_layer_surface()

The graphics framework calls this function to allocate video memory to a layer surface. The prototype is:

disp_surface_t * (*alloc_layer_surface) (
                     disp_adapter_t *adapter,
                     int dispno,
                     int width,
                     int height,
                     unsigned sflags,
                     unsigned hint_flags,
                     int layer_idx,       
                     unsigned fmt_idx,
                     unsigned surface_idx );

The size of the buffer to be allocated is specified in pixels, by the width and height arguments. This function must allocate a disp_surface_t structure and initialize it to describe the allocated memory surface. Set the structure's adapter member to point to the driver's disp_adapter_t structure.

In the case of planar YUV data, the width and height argument would be the same, regardless of whether a Y, a U, or a V plane were being allocated for a given image. It is up to the driver to know how big the actual buffer size which needs to be allocated, should be.

The function must return a pointer to the allocated disp_surface_t and must ensure that the memory it allocates conforms to the surface properties requested by the sflags parameter. This implies that when the function returns, any flags set in sflags are also set in the flags member of the returned surface.

The sflags argument is one of the surface flags as defined in the disp_surface_t section. However, the following flags have no meaning here:

DISP_SURFACE_DISPLAYABLE
DISP_SURFACE_SCALER_DISPLAYABLE

The fmt_idx and surface_idx arguments select the data format of the surface. Some layer formats split the image components across multiple buffers. A planar YUV surface, for example, requires three buffers to store a valid image. The surface_idx argument specifies whether a Y, U, or V buffer gets allocated.

The fmt_idx argument selects the data format of the memory to be allocated.

This function should return a pointer to a structure describing the allocated memory surface, or NULL to indicate failure.

The only valid value for hint_flags is 0.

free_surface()

The graphics framework calls this function to free the video memory associated with the disp_surface_t structure that surf points to, as well as freeing the structure itself. The prototype is:

int (*free_surface) (disp_adapter_t *adapter,
                     disp_surface_t *surface)

mem_avail()

The graphics framework calls this function to determine how much memory is available. The prototype is:

int (*mem_avail) (disp_adapter_t *adapter,
                  unsigned sflags)

This function returns the amount of video memory available, in bytes. However, the memory that's reported as being available must conform to the surface properties specified by sflags.

Classification:

Photon