12. Offscreen Memory Manager

Management of offscreen video memory may be handled by the XFree86 framebuffer manager. Once the offscreen memory manager is running, drivers or extensions may allocate, free or resize areas of offscreen video memory using the following functions (definitions taken from xf86fbman.h):

    typedef struct _FBArea {
        ScreenPtr    pScreen;
        BoxRec       box;
        int          granularity;
        void         (*MoveAreaCallback)(struct _FBArea*, struct _FBArea*)
        void         (*RemoveAreaCallback)(struct _FBArea*)
        DevUnion     devPrivate;
    } FBArea, *FBAreaPtr;

    typedef void (*MoveAreaCallbackProcPtr)(FBAreaPtr from, FBAreaPtr to)
    typedef void (*RemoveAreaCallbackProcPtr)(FBAreaPtr)

    FBAreaPtr xf86AllocateOffscreenArea (
        ScreenPtr pScreen,
        int width, int height,
        int granularity,
        MoveAreaCallbackProcPtr MoveAreaCallback,
        RemoveAreaCallbackProcPtr RemoveAreaCallback,
        pointer privData
    )

    void xf86FreeOffscreenArea (FBAreaPtr area)

    Bool xf86ResizeOffscreenArea (
	FBAreaPtr area
	int w, int h
    )

The function:

Bool xf86FBManagerRunning(ScreenPtr pScreen)

can be used by an extension to check if the driver has initialized the memory manager. The manager is not available if this returns FALSE and the functions above will all fail.

xf86AllocateOffscreenArea() can be used to request a rectangle of dimensions width x height (in pixels) from unused offscreen memory. granularity specifies that the leftmost edge of the rectangle must lie on some multiple of granularity pixels. A granularity of zero means the same thing as a granularity of one - no alignment preference. A MoveAreaCallback can be provided to notify the requester when the offscreen area is moved. If no MoveAreaCallback is supplied then the area is considered to be immovable. The privData field will be stored in the manager's internal structure for that allocated area and will be returned to the requester in the FBArea passed via the MoveAreaCallback. An optional RemoveAreaCallback is provided. If the driver provides this it indicates that the area should be allocated with a lower priority. Such an area may be removed when a higher priority request (one that doesn't have a RemoveAreaCallback) is made. When this function is called, the driver will have an opportunity to do whatever cleanup it needs to do to deal with the loss of the area, but it must finish its cleanup before the function exits since the offscreen memory manager will free the area immediately after.

xf86AllocateOffscreenArea() returns NULL if it was unable to allocate the requested area. When no longer needed, areas should be freed with xf86FreeOffscreenArea().

xf86ResizeOffscreenArea() resizes an existing FBArea. xf86ResizeOffscreenArea() returns TRUE if the resize was successful. If xf86ResizeOffscreenArea() returns FALSE, the original FBArea is left unmodified. Resizing an area maintains the area's original granularity, devPrivate, and MoveAreaCallback. xf86ResizeOffscreenArea() has considerably less overhead than freeing the old area then reallocating the new size, so it should be used whenever possible.

The function:

Bool xf86QueryLargestOffscreenArea(
          ScreenPtr pScreen,
          int *width, int *height,
          int granularity,
          int preferences,
          int priority
)

is provided to query the width and height of the largest single FBArea allocatable given a particular priority. preferences can be one of the following to indicate whether width, height or area should be considered when determining which is the largest single FBArea available.

FAVOR_AREA_THEN_WIDTH
FAVOR_AREA_THEN_HEIGHT
FAVOR_WIDTH_THEN_AREA
FAVOR_HEIGHT_THEN_AREA

priority is one of the following:

PRIORITY_LOW

Return the largest block available without stealing anyone else's space. This corresponds to the priority of allocating a FBArea when a RemoveAreaCallback is provided.

PRIORITY_NORMAL

Return the largest block available if it is acceptable to steal a lower priority area from someone. This corresponds to the priority of allocating a FBArea without providing a RemoveAreaCallback.

PRIORITY_EXTREME

Return the largest block available if all FBAreas that aren't locked down were expunged from memory first. This corresponds to any allocation made directly after a call to xf86PurgeUnlockedOffscreenAreas().

The function:

Bool xf86PurgeUnlockedOffscreenAreas(ScreenPtr pScreen)

is provided as an extreme method to free up offscreen memory. This will remove all removable FBArea allocations.

Initialization of the XFree86 framebuffer manager is done via

Bool xf86InitFBManager(ScreenPtr pScreen, BoxPtr FullBox)

FullBox represents the area of the framebuffer that the manager is allowed to manage. This is typically a box with a width of pScrn->displayWidth and a height of as many lines as can be fit within the total video memory, however, the driver can reserve areas at the extremities by passing a smaller area to the manager.

xf86InitFBManager() must be called before XAA is initialized since XAA uses the manager for it's pixmap cache.

An alternative function is provided to allow the driver to initialize the framebuffer manager with a Region rather than a box.

Bool xf86InitFBManagerRegion(ScreenPtr pScreen,
          RegionPtr FullRegion)

xf86InitFBManagerRegion(), unlike xf86InitFBManager(), does not remove the area used for the visible screen so that area should not be included in the region passed to the function. xf86InitFBManagerRegion() is useful when non-contiguous areas are available to be managed, and is required when multiple framebuffers are stored in video memory (as in the case where an overlay of a different depth is stored as a second framebuffer in offscreen memory).