XFree86 X server ``New Design'' (DRAFT) : The XFree86 X Video Extension (Xv) Device Dependent Layer
Previous: DGA Extension
Next: The Loader

16. The XFree86 X Video Extension (Xv) Device Dependent Layer

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's class. 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 and drw_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 and GetVideo 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
pEncodings

The number of encodings the adaptor is capable of and pointer to the XF86VideoEncodingRec array. The XF86VideoEncodingRec is described later on.

nFormats
pFormats

The number of formats the adaptor is capable of and pointer to the XF86VideoFormatRec array. The XF86VideoFormatRec is described later on.

nPorts
pPortPrivates

The 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:

  1. PutVideo and PutStill are not required when the adaptor type does not contain XvInputMask.
  2. GetVideo and GetStill are not required when the adaptor type does not contain XvOutputMask.

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 a StopVideo 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 the VIDEO_NO_CLIPPING flag is set, the RegionPtr should be ignored by the driver. ClipBoxes is an X-Y banded region identical to those used throughout the server. The clipBoxes represent the visible portions of area determined by drw_x, drw_y, drw_w and drw_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 to GetVideo, once. This to notify the driver the primitive is totally obscured now. A StopVideo call will immediately follow nevertheless. In the case where the VIDEO_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 rectangle rw_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. If cleanup 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:

XV_ENCODING
XV_HUE
XV_SATURATION
XV_BRIGHTNESS
XV_CONTRAST
but the driver may recognize as many atoms as it wishes. If a requested attribute is unknown by the driver it should return BadMatch. XV_ENCODING is the attribute intended to let the client specify which video encoding the particular port should be using (see the description of XF86VideoEncodingRec below). If the requested encoding is unsupported, the driver should return XvBadEncoding. 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 area vid_w × vid_h from the video stream be scaled to rectangle of drw_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 by XvQueryEncodings. The id field is expected to be a unique identifier to allow the client to request a certain encoding via the XV_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 as TrueColor, DirectColor or PseudoColor. 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 are number in size. Currently defined flags are XvGettable and XvSettable 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 by names[] must exist as long as Xv is initialized.


XFree86 X server ``New Design'' (DRAFT) : The XFree86 X Video Extension (Xv) Device Dependent Layer
Previous: DGA Extension
Next: The Loader