`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  (*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.

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