XFree86 offers the X Video Extension which allows clients to treat video
as any another primitive and ``Put'' video into drawables. By default,
the extension reports no video adaptors as being available since the
DDX layer has not been initialized. The driver can initialize the DDX
layer by filling out one or more XF86VideoAdaptorRecs
as described later in this document and passing a list of
XF86VideoAdaptorPtr
pointers to the following function:
Bool xf86XVScreenInit(
ScreenPtr pScreen,
XF86VideoAdaptorPtr *adaptPtrs,
int num)
After doing this, the extension will report video adaptors as being
available, providing the data in their respective
XF86VideoAdaptorRecs
was valid.
xf86XVScreenInit()
copies data from the structure
passed to it so the driver may free it after the initialization. At
the moment, the DDX only supports rendering into Window drawables.
Pixmap rendering will be supported after a sufficient survey of suitable
hardware is completed.
The XF86VideoAdaptorRec
:
typedef struct { unsigned char type; int flags; char *name; int nEncodings; XF86VideoEncodingPtr pEncodings; int nFormats; XF86VideoFormatPtr pFormats; int nPorts; XF86AttributeListPtr pAttributes; DevUnion *pPortPrivates; PutVideoFuncPtr PutVideo; PutStillFuncPtr PutStill; GetVideoFuncPtr GetVideo; GetStillFuncPtr GetStill; StopVideoFuncPtr StopVideo; SetPortAttributeFuncPtr SetPortAttribute; GetPortAttributeFuncPtr GetPortAttribute; QueryBestSizeFuncPtr QueryBestSize; } XF86VideoAdaptorRec, *XF86VideoAdaptorPtr;Each adaptor will have its own XF86VideoAdaptorRec. The fields are as follows:
type
This can be
XvInputMask
,XvOutputMask
or both OR'd together. This refers to the target drawable and is similar to a Window'sclass
.XvInputMask
indicates that the adaptor can put video into a drawable.XvOutputMask
indicates that the adaptor can get video from a drawable.
flags
Currently, the following flags are defined:
VIDEO_NO_CLIPPING
This indicates that the video adaptor does not support clipping. The driver will never receive Get/Put requests where less than the entire area determined by
drw_x
,drw_y
,drw_w
anddrw_h
is visible.
VIDEO_INVERT_CLIPLIST
This indicates that the video driver requires the clip list to contain the regions which are obscured rather than the regions which are are visible.
VIDEO_EXPOSE
This flag applies to
GetStill
andGetVideo
only, it indicates the clip list shall contain obscured regions. Note the source region will still be clipped against the screen bounds. This flag is meant for showing all the contents of the [root] window, if the administrator has no hesitations regarding security.
name
The name of the adaptor.
nEncodings
pEncodingsThe number of encodings the adaptor is capable of and pointer to the
XF86VideoEncodingRec
array. TheXF86VideoEncodingRec
is described later on.
nFormats
pFormatsThe number of formats the adaptor is capable of and pointer to the
XF86VideoFormatRec
array. TheXF86VideoFormatRec
is described later on.
nPorts
pPortPrivatesThe number of ports is the number of separate data streams which the adaptor can handle simultaneously. If you have more than one port, the adaptor is expected to be able to render into more than one window at a time.
pPortPrivates
is an array of pointers or ints - one for each port. A port's private data will be passed to the driver any time the port is requested to do something like put the video or stop the video. In the case where there may be many ports, this enables the driver to know which port the request is intended for. Most commonly, this will contain a pointer to the data structure containing information about the port.
pAttributes
There is an array of
XF86AttributeListRecs
with an entry for each port.
PutVideo PutStill GetVideo GetStill StopVideo SetPortAttribute GetPortAttribute QueryBestSize
These functions define the DDX->driver interface. In each case, the pointer
data
is passed to the driver. This is the port private for that port as described above. All fields are required except under the following conditions:
PutVideo
andPutStill
are not required when the adaptor type does not containXvInputMask
.GetVideo
andGetStill
are not required when the adaptor type does not containXvOutputMask
.These functions should return Success if the operation was completed successfully. They can return
XvBadAlloc
otherwise. Xv DDX will not call a Get/Put function while video is active, rather issue aStopVideo
call first.Earlier versions of Xv DDX had a
ReclipVideo
function, obsolete now. The clip region will be passed directly by the functions below. If theVIDEO_NO_CLIPPING
flag is set, theRegionPtr
should be ignored by the driver.ClipBoxes
is anX-Y
banded region identical to those used throughout the server. The clipBoxes represent the visible portions of area determined bydrw_x
,drw_y
,drw_w
anddrw_h
in the Get/Put function. The boxes are in screen coordinates, are guaranteed not to overlap and an empty region will be passed only toGetVideo
, once. This to notify the driver the primitive is totally obscured now. AStopVideo
call will immediately follow nevertheless. In the case where theVIDEO_INVERT_CLIPLIST
flag is set,clipBoxes
will indicate the areas of the primitive which are obscured rather than the areas visible. The Region must not be altered by the driver and will be deleted when the function returns.
typedef int (* PutVideoFuncPtr)( ScrnInfoPtr pScrn,
short vid_x, short vid_y, short drw_x, short drw_y,
short vid_w, short vid_h, short drw_w, short drw_h,
RegionPtr clipBoxes, pointer data )This indicates that the driver should take a subsection
vid_w × vid_h
at location(vid_x,vid_y)
from the video stream and direct it into the rectanglerw_w × drw_h
at location(drw_x,drw_y)
on the screen, scaling as necessary. Due to the large variations in capabilities of the various hardware expected to be used with this extension, it is not expected that all hardware will be able to do this exactly as described. In that case the driver should just do ``the best it can,'' scaling as closely to the target rectangle as it can without rendering outside of it. In the worst case, the driver can opt to just not turn on the video.
typedef int (* PutStillFuncPtr)( ScrnInfoPtr pScrn,
short vid_x, short vid_y, short drw_x, short drw_y,
short vid_w, short vid_h, short drw_w, short drw_h,
RegionPtr clipBoxes, pointer data )This is same as
PutVideo
except that the driver should place only one frame from the stream on the screen.
typedef int (* GetVideoFuncPtr)( ScrnInfoPtr pScrn,
short vid_x, short vid_y, short drw_x, short drw_y,
short vid_w, short vid_h, short drw_w, short drw_h,
RegionPtr clipBoxes, pointer data )This is same as
PutVideo
except that the driver gets video from the screen and outputs it. The driver should do the best it can to get the requested dimensions correct without reading from an area larger than requested.
typedef int (* GetStillFuncPtr)( ScrnInfoPtr pScrn,
short vid_x, short vid_y, short drw_x, short drw_y,
short vid_w, short vid_h, short drw_w, short drw_h,
RegionPtr clipBoxes, pointer data )This is the same as
GetVideo
except that the driver should place only one frame from the screen into the output stream.
typedef void (* StopVideoFuncPtr)(ScrnInfoPtr pScrn,
pointer data, Bool cleanup)This indicates the the driver should stop displaying the video. This is used to stop both input and output video. The
cleanup
field indicates that the video is being stopped because the client requested it to stop or because the server is exiting the current VT. In that case the driver should deallocate any offscreen memory areas (if there are any) being used to put the video to the screen. Ifcleanup
is not set, the video is being stopped temporarily due to clipping or moving of the window, etc... and video will likely be restarted soon so the driver should not deallocate any offscreen areas associated with that port.typedef int (* SetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
Atom attribute,INT32 value, pointer data)
typedef int (* GetPortAttributeFuncPtr)(ScrnInfoPtr pScrn,
Atom attribute,INT32 *value, pointer data)
A port may have particular attributes such as hue, saturation, brightness or contrast. Xv clients set and get these attribute values by sending attribute strings (Atoms) to the server. Such requests end up at these driver functions. It is recommended that the driver provide at least the following attributes mentioned in the Xv client library docs:
but the driver may recognize as many atoms as it wishes. If a requested attribute is unknown by the driver it should returnXV_ENCODING
XV_HUE
XV_SATURATION
XV_BRIGHTNESS
XV_CONTRASTBadMatch
.XV_ENCODING
is the attribute intended to let the client specify which video encoding the particular port should be using (see the description ofXF86VideoEncodingRec
below). If the requested encoding is unsupported, the driver should returnXvBadEncoding
.Success
should be returned otherwise.
typedef void (* QueryBestSizeFuncPtr)(ScrnInfoPtr pScrn,
Bool motion, short vid_w, short vid_h,
short drw_w, short drw_h,
unsigned int *p_w, unsigned int *p_h, pointer data)
QueryBestSize
provides the client with a way to query what the destination dimensions would end up being if they were to request that an areavid_w × vid_h
from the video stream be scaled to rectangle ofdrw_w × drw_h
on the screen. Since it is not expected that all hardware will be able to get the target dimensions exactly, it is important that the driver provide this function. The returned dimensions must be less than or equal to the requested dimension.
The XF86VideoEncodingRec:
typedef struct { int id; char *name; unsigned short width, height; XvRationalRec rate; } XF86VideoEncodingRec, *XF86VideoEncodingPtr;The
XF86VideoEncodingRec
specifies what encodings the adaptor can support. Most of this data is just informational and for the client's benefit, and is what will be reported byXvQueryEncodings
. Theid
field is expected to be a unique identifier to allow the client to request a certain encoding via theXV_ENCODING
attribute string.
The XF86VideoFormatRec:
typedef struct { char depth; short class; } XF86VideoFormatRec, *XF86VideoFormatPtr;This specifies what visuals the video is viewable in.
depth
is the depth of the visual (not bpp).class
is the visual class such asTrueColor
,DirectColor
orPseudoColor
. Initialization of an adaptor will fail if none of the visuals on that screen are supported.
The XF86AttributeListRec:
typedef struct { int number; int *flags; char **names; } XF86AttributeListRec, *XF86AttributeListPtr;Each port will have one of these indicating the
number
of attributes for that port, an array of names of the attributes and an array of flags associated with each attribute. Both arrays arenumber
in size. Currently defined flags areXvGettable
andXvSettable
which may be OR'd together indicating that attribute is ``gettable'' or ``settable'' by the client. Both arrays can be nulled if number is zero. While the Xv DDX copies most data from these structures and stores it internally, including adaptor and encoding names, the attribute names are not copied, but only their pointers. Because of this, the strings pointed to bynames[]
must exist as long as Xv is initialized.