1#ifndef __XCB_IMAGE_H__
2#define __XCB_IMAGE_H__
3
4/* Copyright (C) 2007 Bart Massey
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a
7 * copy of this software and associated documentation files (the "Software"),
8 * to deal in the Software without restriction, including without limitation
9 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 * and/or sell copies of the Software, and to permit persons to whom the
11 * Software is furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in
14 * all copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
22 *
23 * Except as contained in this notice, the names of the authors or their
24 * institutions shall not be used in advertising or otherwise to promote the
25 * sale, use or other dealings in this Software without prior written
26 * authorization from the authors.
27 */
28
29#include <xcb/xcb.h>
30#include <xcb/shm.h>
31
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37
38/**
39 * @defgroup xcb__image_t XCB Image Functions
40 *
41 * These are functions used to create and manipulate X images.
42 *
43 * The X image format we use is specific to this software,
44 * which is probably a bug; it represents an intermediate
45 * position between the wire format used by the X GetImage
46 * and PutImage requests and standard formats like PBM.  An
47 * image consists of a header of type @ref xcb_image_t
48 * describing the properties of the image, together with a
49 * pointer to the image data itself.
50 *
51 * X wire images come in three formats.  An xy-bitmap is a
52 * bit-packed format that will be expanded to a two-color
53 * pixmap using a GC when sent over the wire by PutImage.
54 * An xy-pixmap is one or more bit-planes, each in the same
55 * format as xy-bitmap.  A z-pixmap is a more conventional
56 * pixmap representation, with each pixel packed into a
57 * word.  Pixmaps are sent and received over the wire only
58 * to/from drawables of their depth.
59 *
60 * Each X server defines, for each depth and format,
61 * properties of images in that format that are sent and
62 * received on the wire.  We refer to this as a "native"
63 * image for a given X server.  It is not uncommon to want
64 * to work with non-native images on the client side, or to
65 * convert between the native images of different servers.
66 *
67 * This library provides several things.  Facilities for
68 * creating and destroying images are, of course, provided.
69 * Wrappers for xcb_get_image() and xcb_put_image() are
70 * provided; these utilize the image header to simplify the
71 * interface.  Routines for getting and putting image pixels
72 * are provided: both a generic form that works with
73 * arbitrary images, and fastpath forms for some common
74 * cases.  Conversion routines are provided for X images;
75 * these routines have been fairly well optimized for the
76 * common cases, and should run fast even on older hardware.
77 * A routine analogous to Xlib's XCreate*FromBitmapData() is
78 * provided for creating X images from xbm-format data; this
79 * routine is in this library only because it is a trivial
80 * use case for the library.
81 *
82 * @{
83 */
84
85
86typedef struct xcb_image_t xcb_image_t;
87
88/**
89 * @struct xcb_image_t
90 * A structure that describes an xcb_image_t.
91 */
92struct xcb_image_t
93{
94  uint16_t           width;   /**< Width in pixels, excluding pads etc. */
95  uint16_t           height;   /**< Height in pixels. */
96  xcb_image_format_t format;   /**< Format. */
97  uint8_t            scanline_pad;   /**< Right pad in bits.  Valid pads
98				      *   are 8, 16, 32.
99				      */
100  uint8_t            depth;   /**< Depth in bits. Valid depths
101			       *   are 1, 4, 8, 16, 24 for z format,
102			       *   1 for xy-bitmap-format, anything
103			       *   for xy-pixmap-format.
104			       */
105  uint8_t            bpp;   /**< Storage per pixel in bits.
106			     *   Must be >= depth. Valid bpp
107			     *   are 1, 4, 8, 16, 24, 32 for z
108			     *   format, 1 for xy-bitmap format,
109			     *   anything for xy-pixmap-format.
110			     */
111  uint8_t	     unit;  /**< Scanline unit in bits for
112			     *   xy formats and for bpp == 1,
113			     *   in which case valid scanline
114			     *   units are 8, 16, 32.  Otherwise,
115			     *   will be max(8, bpp).  Must be >= bpp.
116			     */
117  uint32_t           plane_mask;   /**< When format is
118				    *   xy-pixmap and depth >
119				    *   1, this says which
120				    *   planes are "valid" in
121				    *   some vague sense.
122				    *   Currently used only
123				    *   by xcb_image_get/put_pixel(),
124				    *   and set only by
125				    *   xcb_image_get().
126				    */
127  xcb_image_order_t  byte_order;   /**< Component byte order
128				    *   for z-pixmap, byte
129				    *   order of scanline unit
130				    *   for xy-bitmap and
131				    *   xy-pixmap.  Nybble
132				    *   order for z-pixmap
133				    *   when bpp == 4.
134				    */
135  xcb_image_order_t  bit_order;    /**< Bit order of
136				    *   scanline unit for
137				    *   xy-bitmap and
138				    *   xy-pixmap.
139				    */
140  uint32_t           stride;   /**< Bytes per image row.
141				*   Computable from other
142				*   data, but cached for
143				*   convenience/performance.
144				*/
145  uint32_t           size;   /**< Size of image data in bytes.
146			      *   Computable from other
147			      *   data, but cached for
148			      *   convenience/performance.
149			      */
150  void *             base;   /**< Malloced block of storage that
151			      *   will be freed by
152			      *   @ref xcb_image_destroy() if non-null.
153			      */
154  uint8_t *          data;   /**< The actual image. */
155};
156
157typedef struct xcb_shm_segment_info_t xcb_shm_segment_info_t;
158
159/**
160 * @struct xcb_shm_segment_info_t
161 * A structure that stores the informations needed by the MIT Shm
162 * Extension.
163 */
164struct xcb_shm_segment_info_t
165{
166  xcb_shm_seg_t shmseg;
167  uint32_t    shmid;
168  uint8_t     *shmaddr;
169};
170
171
172/**
173 * Update the cached data of an image.
174 * @param image The image.
175 *
176 * An image's size and stride, among other things, are
177 * cached in its structure.  This function recomputes those
178 * cached values for the given image.
179 * @ingroup xcb__image_t
180 */
181void
182xcb_image_annotate (xcb_image_t *image);
183
184/**
185 * Create a new image.
186 * @param width The width of the image, in pixels.
187 * @param height The height of the image, in pixels.
188 * @param format The format of the image.
189 * @param xpad The scanline pad of the image.
190 * @param depth The depth of the image.
191 * @param bpp The depth of the image storage.
192 * @param unit The unit of image representation, in bits.
193 * @param byte_order The byte order of the image.
194 * @param bit_order The bit order of the image.
195 * @param base The base address of malloced image data.
196 * @param bytes The size in bytes of the storage pointed to by base.
197 *              If base == 0 and bytes == ~0 and data == 0 on
198 *              entry, no storage will be auto-allocated.
199 * @param data The image data.  If data is null and bytes != ~0, then
200 *             an attempt will be made to fill in data; from
201 *             base if it is non-null (and bytes is large enough), else
202 *             by mallocing sufficient storage and filling in base.
203 * @return The new image.
204 *
205 * This function allocates the memory needed for an @ref xcb_image_t structure
206 * with the given properties.  See the description of xcb_image_t for details.
207 * This function initializes and returns a pointer to the
208 * xcb_image_t structure.  It may try to allocate or reserve data for the
209 * structure, depending on how @p base, @p bytes and @p data are set.
210 *
211 * The image must be destroyed with xcb_image_destroy().
212 * @ingroup xcb__image_t
213 */
214xcb_image_t *
215xcb_image_create (uint16_t           width,
216		  uint16_t           height,
217		  xcb_image_format_t format,
218		  uint8_t            xpad,
219		  uint8_t            depth,
220		  uint8_t            bpp,
221		  uint8_t            unit,
222		  xcb_image_order_t  byte_order,
223		  xcb_image_order_t  bit_order,
224		  void *             base,
225		  uint32_t           bytes,
226		  uint8_t *          data);
227
228
229/**
230 * Create a new image in connection-native format.
231 * @param c The connection.
232 * @param width The width of the image, in pixels.
233 * @param height The height of the image, in pixels.
234 * @param format The format of the image.
235 * @param depth The depth of the image.
236 * @param base The base address of malloced image data.
237 * @param bytes The size in bytes of the storage pointed to by base.
238 *              If base == 0 and bytes == ~0 and data == 0 on
239 *              entry, no storage will be auto-allocated.
240 * @param data The image data.  If data is null and bytes != ~0, then
241 *             an attempt will be made to fill in data; from
242 *             base if it is non-null (and bytes is large enough), else
243 *             by mallocing sufficient storage and filling in base.
244 * @return The new image.
245 *
246 * This function calls @ref xcb_image_create() with the given
247 * properties, and with the remaining properties chosen
248 * according to the "native format" with the given
249 * properties on the current connection.
250 *
251 * It is usual to use this rather
252 * than calling xcb_image_create() directly.
253 * @ingroup xcb__image_t
254 */
255xcb_image_t *
256xcb_image_create_native (xcb_connection_t *  c,
257			 uint16_t            width,
258			 uint16_t            height,
259			 xcb_image_format_t  format,
260			 uint8_t             depth,
261			 void *              base,
262			 uint32_t            bytes,
263			 uint8_t *           data);
264
265
266/**
267 * Destroy an image.
268 * @param image The image to be destroyed.
269 *
270 * This function frees the memory associated with the @p image
271 * parameter.  If its base pointer is non-null, it frees
272 * that also.
273 * @ingroup xcb__image_t
274 */
275void
276xcb_image_destroy (xcb_image_t *image);
277
278
279/**
280 * Get an image from the X server.
281 * @param conn The connection to the X server.
282 * @param draw The drawable to get the image from.
283 * @param x The x coordinate in pixels, relative to the origin of the
284 * drawable and defining the upper-left corner of the rectangle.
285 * @param y The y coordinate in pixels, relative to the origin of the
286 * drawable and defining the upper-left corner of the rectangle.
287 * @param width The width of the subimage in pixels.
288 * @param height The height of the subimage in pixels.
289 * @param plane_mask The plane mask.  See the protocol document for details.
290 * @param format The format of the image.
291 * @return The subimage of @p draw defined by @p x, @p y, @p w, @p h.
292 *
293
294 * This function returns a new image taken from the
295 * given drawable @p draw.
296 * The image will be in connection native format. If the @p format
297 * is xy-bitmap and the @p plane_mask masks bit planes out, those
298 * bit planes will be made part of the returned image anyway,
299 * by zero-filling them; this will require a fresh memory allocation
300 * and some copying.  Otherwise, the resulting image will use the
301 * xcb_get_image_reply() record as its backing store.
302 *
303 * If a problem occurs, the function returns null.
304 * @ingroup xcb__image_t
305 */
306xcb_image_t *
307xcb_image_get (xcb_connection_t *  conn,
308	       xcb_drawable_t      draw,
309	       int16_t             x,
310	       int16_t             y,
311	       uint16_t            width,
312	       uint16_t            height,
313	       uint32_t            plane_mask,
314	       xcb_image_format_t  format);
315
316
317/**
318 * Put an image onto the X server.
319 * @param conn The connection to the X server.
320 * @param draw The draw you get the image from.
321 * @param gc The graphic context.
322 * @param image The image you want to combine with the rectangle.
323 * @param x The x coordinate, which is relative to the origin of the
324 * drawable and defines the x coordinate of the upper-left corner of the
325 * rectangle.
326 * @param y The y coordinate, which is relative to the origin of the
327 * drawable and defines the x coordinate of the upper-left corner of
328 * the rectangle.
329 * @param left_pad Notionally shift an xy-bitmap or xy-pixmap image
330 * to the right some small amount, for some reason.  XXX Not clear
331 * this is currently supported correctly.
332 * @return The cookie returned by xcb_put_image().
333 *
334 * This function combines an image with a rectangle of the
335 * specified drawable @p draw. The image must be in native
336 * format for the connection.  The image is drawn at the
337 * specified location in the drawable. For the xy-bitmap
338 * format, the foreground pixel in @p gc defines the source
339 * for the one bits in the image, and the background pixel
340 * defines the source for the zero bits. For xy-pixmap and
341 * z-pixmap formats, the depth of the image must match the
342 * depth of the drawable; the gc is ignored.
343 *
344 * @ingroup xcb__image_t
345 */
346xcb_void_cookie_t
347xcb_image_put (xcb_connection_t *  conn,
348	       xcb_drawable_t      draw,
349	       xcb_gcontext_t      gc,
350	       xcb_image_t *       image,
351	       int16_t             x,
352	       int16_t             y,
353	       uint8_t             left_pad);
354
355
356/**
357 * Check image for or convert image to native format.
358 * @param c The connection to the X server.
359 * @param image The image.
360 * @param convert  If 0, just check the image for native format.
361 * Otherwise, actually convert it.
362 * @return Null if the image is not in native format and can or will not
363 * be converted.  Otherwise, the native format image.
364 *
365 * Each X display has its own "native format" for images of a given
366 * format and depth.  This function either checks whether the given
367 * @p image is in native format for the given connection @p c, or
368 * actually tries to convert the image to native format, depending
369 * on whether @p convert is true or false.
370 *
371 * When @p convert is true, and the image is not in native format
372 * but can be converted, it will be, and a pointer to the new image
373 * will be returned.  The image passed in will be unharmed in this
374 * case; it is the caller's responsibility to check that the returned
375 * pointer is different and to dispose of the old image if desired.
376 * @ingroup xcb__image_t
377 */
378xcb_image_t *
379xcb_image_native (xcb_connection_t *  c,
380		  xcb_image_t *       image,
381		  int                 convert);
382
383
384/**
385 * Put a pixel to an image.
386 * @param image The image.
387 * @param x The x coordinate of the pixel.
388 * @param y The y coordinate of the pixel.
389 * @param pixel The new pixel value.
390 *
391 * This function overwrites the pixel in the given @p image with the
392 * specified @p pixel value (in client format). The image must contain the @p x
393 * and @p y coordinates, as no clipping is done.  This function honors
394 * the plane-mask for xy-pixmap images.
395 * @ingroup xcb__image_t
396 */
397void
398xcb_image_put_pixel (xcb_image_t *image,
399		     uint32_t x,
400		     uint32_t y,
401		     uint32_t pixel);
402
403/**
404 * Get a pixel from an image.
405 * @param image The image.
406 * @param x The x coordinate of the pixel.
407 * @param y The y coordinate of the pixel.
408 * @return The pixel value.
409 *
410 * This function retrieves a pixel from the given @p image.
411 * The image must contain the @p x
412 * and @p y coordinates, as no clipping is done.  This function honors
413 * the plane-mask for xy-pixmap images.
414 * @ingroup xcb__image_t
415 */
416uint32_t
417xcb_image_get_pixel (xcb_image_t *image,
418		     uint32_t x,
419		     uint32_t y);
420
421
422/**
423 * Convert an image to a new format.
424 * @param src Source image.
425 * @param dst Destination image.
426 * @return The @p dst image, or null on error.
427 *
428 * This function tries to convert the image data of the @p
429 * src image to the format implied by the @p dst image,
430 * overwriting the current destination image data.
431 * The source and destination must have the same
432 * width, height, and depth.  When the source and destination
433 * are already the same format, a simple copy is done.  Otherwise,
434 * when the destination has the same bits-per-pixel/scanline-unit
435 * as the source, an optimized copy routine (thanks to Keith Packard)
436 * is used for the conversion.  Otherwise, the copy is done the
437 * slow, slow way with @ref xcb_image_get_pixel() and
438 * @ref xcb_image_put_pixel() calls.
439 * @ingroup xcb__image_t
440 */
441xcb_image_t *
442xcb_image_convert (xcb_image_t *  src,
443		   xcb_image_t *  dst);
444
445
446/**
447 * Extract a subimage of an image.
448 * @param image Source image.
449 * @param x X coordinate of subimage.
450 * @param y Y coordinate of subimage.
451 * @param width Width of subimage.
452 * @param height Height of subimage.
453 * @param base Base of memory allocation.
454 * @param bytes Size of base allocation.
455 * @param data Memory allocation.
456 * @return The subimage, or null on error.
457 *
458 * Given an image, this function extracts the subimage at the
459 * given coordinates.  The requested subimage must be entirely
460 * contained in the source @p image.  The resulting image will have the same
461 * general image parameters as the source image.  The @p base, @p bytes,
462 * and @p data arguments are passed to @ref xcb_create_image() unaltered
463 * to create the destination image---see its documentation for details.
464 *
465 * @ingroup xcb__image_t
466 */
467xcb_image_t *
468xcb_image_subimage(xcb_image_t *  image,
469		   uint32_t       x,
470		   uint32_t       y,
471		   uint32_t       width,
472		   uint32_t       height,
473		   void *         base,
474		   uint32_t       bytes,
475		   uint8_t *      data);
476
477
478/*
479 * Shm stuff
480 */
481
482/**
483 * Put the data of an xcb_image_t onto a drawable using the MIT Shm
484 * Extension.
485 * @param conn The connection to the X server.
486 * @param draw The draw you get the image from.
487 * @param gc The graphic context.
488 * @param image The image you want to combine with the rectangle.
489 * @param shminfo A @ref xcb_shm_segment_info_t structure.
490 * @param src_x The offset in x from the left edge of the image
491 * defined by the xcb_image_t structure.
492 * @param src_y The offset in y from the left edge of the image
493 * defined by the xcb_image_t structure.
494 * @param dest_x The x coordinate, which is relative to the origin of the
495 * drawable and defines the x coordinate of the upper-left corner of the
496 * rectangle.
497 * @param dest_y The y coordinate, which is relative to the origin of the
498 * drawable and defines the x coordinate of the upper-left corner of
499 * the rectangle.
500 * @param src_width The width of the subimage, in pixels.
501 * @param src_height The height of the subimage, in pixels.
502 * @param send_event Indicates whether or not a completion event
503 * should occur when the image write is complete.
504 * @return 1 is no problems occurs.
505 *
506 * This function combines an image in memory with a shape of the
507 * specified drawable. The section of the image defined by the @p x, @p y,
508 * @p width, and @p height arguments is drawn on the specified part of
509 * the drawable. If XYBitmap format is used, the depth must be
510 * one, or a``BadMatch'' error results. The foreground pixel in the
511 * Graphic Context @p gc defines the source for the one bits in the
512 * image, and the background pixel defines the source for the zero
513 * bits. For XYPixmap and ZPixmap, the depth must match the depth of
514 * the drawable, or a ``BadMatch'' error results.
515 *
516 * If a problem occurs, the functons returns @c 0. Otherwise, it
517 * returns @c 1.
518 * @ingroup xcb__image_t
519 */
520xcb_image_t *
521xcb_image_shm_put (xcb_connection_t *      conn,
522		   xcb_drawable_t          draw,
523		   xcb_gcontext_t          gc,
524		   xcb_image_t *           image,
525		   xcb_shm_segment_info_t  shminfo,
526		   int16_t                 src_x,
527		   int16_t                 src_y,
528		   int16_t                 dest_x,
529		   int16_t                 dest_y,
530		   uint16_t                src_width,
531		   uint16_t                src_height,
532		   uint8_t                 send_event);
533
534
535/**
536 * Read image data into a shared memory xcb_image_t.
537 * @param conn The connection to the X server.
538 * @param draw The draw you get the image from.
539 * @param image The image you want to combine with the rectangle.
540 * @param shminfo A @ref xcb_shm_segment_info_t structure.
541 * @param x The x coordinate, which are relative to the origin of the
542 * drawable and define the upper-left corner of the rectangle.
543 * @param y The y coordinate, which are relative to the origin of the
544 * drawable and define the upper-left corner of the rectangle.
545 * @param plane_mask The plane mask.
546 * @return The subimage of @p draw defined by @p x, @p y, @p w, @p h.
547 *
548 * This function reads image data into a shared memory xcb_image_t where
549 * @p conn is the connection to the X server, @p draw is the source
550 * drawable, @p image is the destination xcb_image_t, @p x and @p y are offsets
551 * within the drawable, and @p plane_mask defines which planes are to be
552 * read.
553 *
554 * If a problem occurs, the functons returns @c 0. It returns 1
555 * otherwise.
556 * @ingroup xcb__image_t
557 */
558int xcb_image_shm_get (xcb_connection_t *      conn,
559		       xcb_drawable_t          draw,
560		       xcb_image_t *           image,
561		       xcb_shm_segment_info_t  shminfo,
562		       int16_t                 x,
563		       int16_t                 y,
564		       uint32_t                plane_mask);
565
566
567/**
568 * Create an image from user-supplied bitmap data.
569 * @param data Image data in packed bitmap format.
570 * @param width Width in bits of image data.
571 * @param height Height in bits of image data.
572 * @return The image constructed from the image data, or 0 on error.
573 *
574 * This function creates an image from the user-supplied
575 * bitmap @p data.  The bitmap data is assumed to be in
576 * xbm format (i.e., 8-bit scanline unit, LSB-first, 8-bit pad).
577 * @ingroup xcb__image_t
578 */
579xcb_image_t *
580xcb_image_create_from_bitmap_data (uint8_t *           data,
581				   uint32_t            width,
582				   uint32_t            height);
583
584/**
585 * Create a pixmap from user-supplied bitmap data.
586 * @param display The connection to the X server.
587 * @param d The parent drawable for the pixmap.
588 * @param data Image data in packed bitmap format.
589 * @param width Width in bits of image data.
590 * @param height Height in bits of image data.
591 * @param depth Depth of the desired pixmap.
592 * @param fg Pixel for one-bits of pixmaps with depth larger than one.
593 * @param bg Pixel for zero-bits of pixmaps with depth larger than one.
594 * @param gcp If this pointer is non-null, the GC created to
595 * fill in the pixmap is stored here; it will have its foreground
596 * and background set to the supplied value.  Otherwise, the GC
597 * will be freed.
598 * @return The pixmap constructed from the image data, or 0 on error.
599 *
600 * This function creates a pixmap from the user-supplied
601 * bitmap @p data.  The bitmap data is assumed to be in
602 * xbm format (i.e., 8-bit scanline unit, LSB-first, 8-bit pad).
603 * If @p depth is greater than 1, the
604 * bitmap will be expanded to a pixmap using the given
605 * foreground and background pixels @p fg and @p bg.
606 * @ingroup xcb__image_t
607 */
608xcb_pixmap_t
609xcb_create_pixmap_from_bitmap_data (xcb_connection_t *  display,
610				    xcb_drawable_t      d,
611				    uint8_t *           data,
612				    uint32_t            width,
613				    uint32_t            height,
614				    uint32_t            depth,
615				    uint32_t            fg,
616				    uint32_t            bg,
617				    xcb_gcontext_t *    gcp);
618
619
620/**
621 * @}
622 */
623
624
625#ifdef __cplusplus
626}
627#endif
628
629
630#endif /* __XCB_IMAGE_H__ */
631