1
2Addendum to the Xv Client library documentation
3===============================================
4
5  The following features are new to version 2.2
6
71) In addition to XvInputMask and XvOutputMask masks in the type field
8   of the XvAdaptorInfo there are 3 new bits defined - XvVideoMask,
9   XvStillMask and XvImageMask indicating that the adaptor is capable
10   of video, still or image primitives respectively.
11
122) A new function and structure is defined to allow querying
13   port attributes.
14
15typedef struct {
16  int flags;
17  int min_value;
18  int max_value;
19  char *name;
20} XvAttribute;
21
22  flags  -   May be XvGettable or XvSettable or both OR'd together
23	     indicating the particular attribute is readable, writeable
24	     or readable and writeable.
25
26  min_value, max_value -  Indicate the minimum and maximum attribute
27	     values which are valid for the driver.
28
29  name -  A string describing the name of the attribute that may be used
30	     to retrieve the Atom for the particular attribute.
31
32
33extern XvAttribute* XvQueryPortAttributes(
34  Display*                /* display */,
35  XvPortID                /* port */,
36  int*                    /* number */
37);
38
39   XvQueryPortAttributes returns the number of attributes and an
40   array of XvAttributes valid for the given port.  The array may
41   be freed with XFree().
42
43
443)  The X Video Extension (Xv) is extended to support client images in
45alternate colorspaces (XvImages) in the following way.
46
47  Xv Adaptors which are capable of displaying XvImages will have
48  the XvImageMask field set in the type field of the XvAdaptorInfo.
49
50  XvImage formats supported by the port may be queried with
51  XvListImageFormats().
52
53  XvImages may be created with the help of XvCreateImage() or
54  XvShmCreateImage();
55
56  XvImages may be displayed with XvPutImage() or XvShmPutImage().
57
58  The Port attributes of the port specified in the Xv(Shm)PutImage
59  command will be valid for the image operation when applicable.
60
61  There will be a port encoding with the name "XV_IMAGE".  The
62  width and height of that encoding will indicate the maximum
63  source image size.
64
65typedef struct {
66  int id;                      /* Unique descriptor for the format */
67  int type;                    /* XvRGB, XvYUV */
68  int byte_order;              /* LSBFirst, MSBFirst */
69  char guid[16];               /* Globally Unique IDentifier */
70  int bits_per_pixel;
71  int format;                  /* XvPacked, XvPlanar */
72  int num_planes;
73
74  /* for RGB formats */
75  int depth;
76  unsigned int red_mask;
77  unsigned int green_mask;
78  unsigned int blue_mask;
79
80  /* for YUV formats */
81  unsigned int y_sample_bits;
82  unsigned int u_sample_bits;
83  unsigned int v_sample_bits;
84  unsigned int horz_y_period;
85  unsigned int horz_u_period;
86  unsigned int horz_v_period;
87  unsigned int vert_y_period;
88  unsigned int vert_u_period;
89  unsigned int vert_v_period;
90  char component_order[32];    /* eg. UYVY */
91  int scanline_order;          /* XvTopToBottom, XvBottomToTop */
92} XvImageFormatValues;
93
94
95   id -  A unique descriptor for the format.  This is often the FOURCC
96	 for the format, when applicable.  This id is used to describe
97	 the format during XvImage creation.
98
99   type - XvRGB or XvYUV.
100
101   byte_order -  The byte order of the image.  It is either LSBFirst
102	         or MSBFirst.
103
104   guid -  The Globally Unique IDentifier (also known as Universally Unique
105	   IDentifier).  When not applicable, all characters are NULL.
106
107   bits_per_pixel - The bits taken up (but not necessarily used) by each
108                    pixel.  Note that for some planar formats which have
109                    fractional bits per pixel (such as IF09) this number
110                    may be rounded _down_.
111
112   format - XvPacked or XvPlanar.
113
114   num_planes - The number of planes in planar formats.
115
116   depth - Significant bits per pixel.
117
118   red_mask, green_mask, blue_mask -  The red, green and blue bitmasks
119				      (RGB formats only).
120
121
122   ?_sample_bits -  The size of each sample in bits (YUV formats only).
123
124   horz_?_period, vert_?_period -  The period (in pixels) on which samples
125                                   occur in the horizontal and vertical
126                                   directions (YUV formats only).
127
128   component_order -  Upper case ascii characters representing the order
129                      that samples are stored within packed formats.
130                      For planar formats this represents the ordering of
131                      the planes.
132
133   scanline_order - XvTopToBottom or XvBottomToTop.
134
135Note:  Since some formats (particularly some planar YUV formats) may not
136       be completely defined by the parameters above, the guid, when
137       available, should provide the most accurate description of the
138       format.
139
140
141
142XvImageFormatValues * XvListImageFormats (
143   Display 	*display,
144   XvPortID 	port_id,
145   int 		*count_return
146);
147
148   Returns the XvImageFormatValues supported by the specified port.
149This list should be freed with XFree().
150
151
152typedef struct {
153   int id;
154   int width, height;
155   int data_size;
156   int num_planes;
157   int *pitches;
158   int *offsets;
159   char *data;
160   XPointer obdata;
161} XvImage;
162
163   id - XvImageFormatValues id.
164
165   width, height - The width and height of the image in pixels.
166
167   int data_size - The size of the data buffer in bytes.
168
169   num_planes -  The number of image planes.
170
171   pitches -  An array of size num_planes indicating the scanline pitch
172              in bytes.  Each plane may have a different pitch.
173
174   offsets -  An array of size num_planes indicating the byte offset
175              from "data" to the start of each plane.
176
177   data -  A pointer to the start of the data buffer.
178
179   obdata -  A private field for holding SHM info.  This field will be
180             set up by the client libraries so the programmer will
181             generally need not be concerned with this field.
182
183XvImage * XvCreateImage (
184   Display *display,
185   XvPortID port,
186   int id,
187   char *data,
188   int width,
189   int height
190);
191
192   display - Specifies the connection to the Xserver.
193   port    - Specifies the port the XvImage will be used with.
194   id      - Specifies the format of the image to be created by
195	     the XvImageFormatValues id.
196   data    - Specifies the image data.
197   width
198   height  - Specifies the desired width and height of the image.
199
200   This function is similar to XCreateImage.  The library will
201allocate the XvImage structure and fill out all fields except for
202"data".  Width and height may be enlarged in some YUV formats.
203The size of the data buffer that needs to be allocated will be
204give in the "data_size" field in the XvImage.  Image data is
205not allocated by this function.  The client may pass a pointer
206to the preallocated memory as "data" or may allocate the memory
207and fill in the XvImage structure's data field after the
208"data_size" field has been filled out by the server.  The XvImage
209structure may be freed by XFree();
210
211
212XvImage * XvShmCreateImage (
213   Display *display,
214   XvPortID port,
215   int id,
216   char* data,
217   int width,
218   int height,
219   XShmSegmentInfo *shminfo
220);
221
222   This function is similar to XShmCreateImage.  The library will
223allocate the XvImage structure and fill out all fields except for
224"data".  Width and height may be enlarged in some YUV formats.
225The size of the data buffer that needs to be allocated will be
226give in the "data_size" field in the XvImage.  Image data is
227not allocated by this function.  The client may pass a pointer
228to the preallocated memory as "data" or may allocate the memory
229and fill in the XvImage structure's data field after the
230"data_size" field has been filled out by the server.  The XvImage
231structure may be freed by XFree();
232
233
234XvPutImage (
235   Display *display,
236   XvPortID id,
237   Drawable d,
238   GC gc,
239   XvImage *image,
240   int src_x,
241   int src_y,
242   unsigned int src_w,
243   unsigned int src_h,
244   int dest_x,
245   int dest_y,
246   unsigned int dest_w,
247   unsigned int dest_h,
248);
249
250XvShmPutImage (
251   Display *display,
252   XvPortID id,
253   Drawable d,
254   GC gc,
255   XvImage *image,
256   int src_x,
257   int src_y,
258   unsigned int src_w,
259   unsigned int src_h,
260   int dest_x,
261   int dest_y,
262   unsigned int dest_w,
263   unsigned int dest_h,
264   Bool send_event
265);
266
267   display - The connection to the X-Server.
268
269   id -  The port id of a port on an XvImage capable adaptor.
270
271   d - The target drawable.
272
273   gc - the graphics context specifying the clip mask to use, if any.
274
275   image - A pointer to the XvImage to be displayed.
276
277   src_? - The portion of the XvImage to be displayed.
278
279   dest_? - The portion of the destination drawable to be filled by the image.
280
281   send_event - Indicates whether or not an XShmCompletionEvent should be
282                sent.  If sent, the event's major_code and minor_code
283                fields will indicate the Xv extension's major code and
284                XvShmPutImage's minor code.
285
286Shared memory segments are attached/detached with XShmAttach/Detach.
287
288
289Some of the possible Errors:
290
291   BadDrawable   - The specified drawable does not exist.
292   BadContext    - The specified GC does not exist.
293   BadMatch      - Incompatible arguments such as a port that isn't capable
294                   of displaying XvImages.
295   XvBadPort     - The specified port does not exist.
296   BadAlloc      - The server was unable to allocate resources required
297                   to complete the operation.
298   BadValue      - Some numeric value falls outside the range of the
299                   values accepted by the request.
300   BadShmSegCode - An invalid shared memory segment.
301