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 a pointer to the source image if no problem occurs, otherwise 0.
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 * @ingroup xcb__image_t
517 */
518xcb_image_t *
519xcb_image_shm_put (xcb_connection_t * conn,
520 xcb_drawable_t draw,
521 xcb_gcontext_t gc,
522 xcb_image_t * image,
523 xcb_shm_segment_info_t shminfo,
524 int16_t src_x,
525 int16_t src_y,
526 int16_t dest_x,
527 int16_t dest_y,
528 uint16_t src_width,
529 uint16_t src_height,
530 uint8_t send_event);
531
532
533/**
534 * Read image data into a shared memory xcb_image_t.
535 * @param conn The connection to the X server.
536 * @param draw The draw you get the image from.
537 * @param image The image you want to combine with the rectangle.
538 * @param shminfo A @ref xcb_shm_segment_info_t structure.
539 * @param x The x coordinate, which are relative to the origin of the
540 * drawable and define the upper-left corner of the rectangle.
541 * @param y The y coordinate, which are relative to the origin of the
542 * drawable and define the upper-left corner of the rectangle.
543 * @param plane_mask The plane mask.
544 * @return The subimage of @p draw defined by @p x, @p y, @p w, @p h.
545 *
546 * This function reads image data into a shared memory xcb_image_t where
547 * @p conn is the connection to the X server, @p draw is the source
548 * drawable, @p image is the destination xcb_image_t, @p x and @p y are offsets
549 * within the drawable, and @p plane_mask defines which planes are to be
550 * read.
551 *
552 * If a problem occurs, the function returns @c 0. It returns 1
553 * otherwise.
554 * @ingroup xcb__image_t
555 */
556int xcb_image_shm_get (xcb_connection_t * conn,
557 xcb_drawable_t draw,
558 xcb_image_t * image,
559 xcb_shm_segment_info_t shminfo,
560 int16_t x,
561 int16_t y,
562 uint32_t plane_mask);
563
564
565/**
566 * Create an image from user-supplied bitmap data.
567 * @param data Image data in packed bitmap format.
568 * @param width Width in bits of image data.
569 * @param height Height in bits of image data.
570 * @return The image constructed from the image data, or 0 on error.
571 *
572 * This function creates an image from the user-supplied
573 * bitmap @p data. The bitmap data is assumed to be in
574 * xbm format (i.e., 8-bit scanline unit, LSB-first, 8-bit pad).
575 * @ingroup xcb__image_t
576 */
577xcb_image_t *
578xcb_image_create_from_bitmap_data (uint8_t * data,
579 uint32_t width,
580 uint32_t height);
581
582/**
583 * Create a pixmap from user-supplied bitmap data.
584 * @param display The connection to the X server.
585 * @param d The parent drawable for the pixmap.
586 * @param data Image data in packed bitmap format.
587 * @param width Width in bits of image data.
588 * @param height Height in bits of image data.
589 * @param depth Depth of the desired pixmap.
590 * @param fg Pixel for one-bits of pixmaps with depth larger than one.
591 * @param bg Pixel for zero-bits of pixmaps with depth larger than one.
592 * @param gcp If this pointer is non-null, the GC created to
593 * fill in the pixmap is stored here; it will have its foreground
594 * and background set to the supplied value. Otherwise, the GC
595 * will be freed.
596 * @return The pixmap constructed from the image data, or 0 on error.
597 *
598 * This function creates a pixmap from the user-supplied
599 * bitmap @p data. The bitmap data is assumed to be in
600 * xbm format (i.e., 8-bit scanline unit, LSB-first, 8-bit pad).
601 * If @p depth is greater than 1, the
602 * bitmap will be expanded to a pixmap using the given
603 * foreground and background pixels @p fg and @p bg.
604 * @ingroup xcb__image_t
605 */
606xcb_pixmap_t
607xcb_create_pixmap_from_bitmap_data (xcb_connection_t * display,
608 xcb_drawable_t d,
609 uint8_t * data,
610 uint32_t width,
611 uint32_t height,
612 uint32_t depth,
613 uint32_t fg,
614 uint32_t bg,
615 xcb_gcontext_t * gcp);
616
617
618/**
619 * @}
620 */
621
622
623#ifdef __cplusplus
624}
625#endif
626
627
628#endif /* __XCB_IMAGE_H__ */
629

source code of include/xcb/xcb_image.h