XFree86 server 4.x Design (DRAFT) : Offscreen Memory Manager
Previous: Modules, Drivers, Include Files and Interface Issues
Next: Colormap Handling

## 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).

XFree86 server 4.x Design (DRAFT) : Offscreen Memory Manager
Previous: Modules, Drivers, Include Files and Interface Issues
Next: Colormap Handling