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 aRemoveAreaCallback
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 aRemoveAreaCallback
.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 toxf86PurgeUnlockedOffscreenAreas()
.
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).