1XPutImage(3X11) XLIB FUNCTIONS XPutImage(3X11)
2
6 XPutImage, XGetImage, XGetSubImage - transfer images
7
9 int XPutImage(Display *display, Drawable d, GC gc, XImage *image, int
10 src_x, int src_y, int dest_x, int dest_y, unsigned int width,
11 unsigned int height);
12 XImage *XGetImage(Display *display, Drawable d, int x, int y, unsigned
14 int width, unsigned int height, unsigned long plane_mask, int
15 format);
16 XImage *XGetSubImage(Display *display, Drawable d, int x, int y,
18 unsigned int width, unsigned int height, unsigned long
19 plane_mask, int format, XImage *dest_image, int dest_x, dest_y);
20
22 d Specifies the drawable.
23 dest_image
25 Specifies the destination image.
26 dest_x
32 dest_y Specify the x and y coordinates, which are relative to the
33 origin of the drawable and are the coordinates of the subim‐
34 age or which are relative to the origin of the destination
35 rectangle, specify its upper-left corner, and determine where
36 the subimage is placed in the destination image.
37 display Specifies the connection to the X server.
39 format Specifies the format for the image. You can pass XYPixmap or
41 ZPixmap.
42 gc Specifies the GC.
44 image Specifies the image you want combined with the rectangle.
46 plane_mask
48 Specifies the plane mask.
49 src_x Specifies the offset in X from the left edge of the image
51 defined by the XImage structure.
52 src_y Specifies the offset in Y from the top edge of the image
54 defined by the XImage structure.
55 width
57 height Specify the width and height of the subimage, which define
58 the dimensions of the rectangle.
59 x
62 y Specify the x and y coordinates, which are relative to the
63 origin of the drawable and define the upper-left corner of
64 the rectangle.
65
67 The XPutImage function combines an image with a rectangle of the speci‐
68 fied drawable. The section of the image defined by the src_x, src_y,
69 width, and height arguments is drawn on the specified part of the draw‐
70 able. If XYBitmap format is used, the depth of the image must be one,
71 or a BadMatch error results. The foreground pixel in the GC defines
72 the source for the one bits in the image, and the background pixel
73 defines the source for the zero bits. For XYPixmap and ZPixmap, the
74 depth of the image must match the depth of the drawable, or a BadMatch
75 error results.
76 If the characteristics of the image (for example, byte_order and bit‐
78 map_unit) differ from what the server requires, XPutImage automatically
79 makes the appropriate conversions.
80 This function uses these GC components: function, plane-mask, subwin‐
82 dow-mode, clip-x-origin, clip-y-origin, and clip-mask. It also uses
83 these GC mode-dependent components: foreground and background.
84 XPutImage can generate BadDrawable, BadGC, BadMatch, and BadValue
86 errors.
87 The XGetImage function returns a pointer to an XImage structure. This
89 structure provides you with the contents of the specified rectangle of
90 the drawable in the format you specify. If the format argument is XYP‐
91 ixmap, the image contains only the bit planes you passed to the
92 plane_mask argument. If the plane_mask argument only requests a subset
93 of the planes of the display, the depth of the returned image will be
94 the number of planes requested. If the format argument is ZPixmap,
95 XGetImage returns as zero the bits in all planes not specified in the
96 plane_mask argument. The function performs no range checking on the
97 values in plane_mask and ignores extraneous bits.
98 XGetImage returns the depth of the image to the depth member of the
100 XImage structure. The depth of the image is as specified when the
101 drawable was created, except when getting a subset of the planes in
102 XYPixmap format, when the depth is given by the number of bits set to 1
103 in plane_mask.
104 If the drawable is a pixmap, the given rectangle must be wholly con‐
106 tained within the pixmap, or a BadMatch error results. If the drawable
107 is a window, the window must be viewable, and it must be the case that
108 if there were no inferiors or overlapping windows, the specified rec‐
109 tangle of the window would be fully visible on the screen and wholly
110 contained within the outside edges of the window, or a BadMatch error
111 results. Note that the borders of the window can be included and read
112 with this request. If the window has backing-store, the backing-store
113 contents are returned for regions of the window that are obscured by
114 noninferior windows. If the window does not have backing-store, the
115 returned contents of such obscured regions are undefined. The returned
116 contents of visible regions of inferiors of a different depth than the
117 specified window's depth are also undefined. The pointer cursor image
118 is not included in the returned contents. If a problem occurs, XGetIm‐
119 age returns NULL.
120 XGetImage can generate BadDrawable, BadMatch, and BadValue errors.
122 The XGetSubImage function updates dest_image with the specified subim‐
124 age in the same manner as XGetImage. If the format argument is XYP‐
125 ixmap, the image contains only the bit planes you passed to the
126 plane_mask argument. If the format argument is ZPixmap, XGetSubImage
127 returns as zero the bits in all planes not specified in the plane_mask
128 argument. The function performs no range checking on the values in
129 plane_mask and ignores extraneous bits. As a convenience, XGetSubImage
130 returns a pointer to the same XImage structure specified by dest_image.
131 The depth of the destination XImage structure must be the same as that
133 of the drawable. If the specified subimage does not fit at the speci‐
134 fied location on the destination image, the right and bottom edges are
135 clipped. If the drawable is a pixmap, the given rectangle must be
136 wholly contained within the pixmap, or a BadMatch error results. If
137 the drawable is a window, the window must be viewable, and it must be
138 the case that if there were no inferiors or overlapping windows, the
139 specified rectangle of the window would be fully visible on the screen
140 and wholly contained within the outside edges of the window, or a Bad‐
141 Match error results. If the window has backing-store, then the back‐
142 ing-store contents are returned for regions of the window that are
143 obscured by noninferior windows. If the window does not have backing-
144 store, the returned contents of such obscured regions are undefined.
145 The returned contents of visible regions of inferiors of a different
146 depth than the specified window's depth are also undefined. If a prob‐
147 lem occurs, XGetSubImage returns NULL.
148 XGetSubImage can generate BadDrawable, BadGC, BadMatch, and BadValue
150 errors.
151
153 BadDrawable
154 A value for a Drawable argument does not name a defined Win‐
155 dow or Pixmap.
156 BadGC A value for a GContext argument does not name a defined GCon‐
158 text.
159 BadMatch An InputOnly window is used as a Drawable.
161 BadMatch Some argument or pair of arguments has the correct type and
163 range but fails to match in some other way required by the
164 request.
165 BadValue Some numeric value falls outside the range of values accepted
167 by the request. Unless a specific range is specified for an
168 argument, the full range defined by the argument's type is
169 accepted. Any argument defined as a set of alternatives can
170 generate this error.
171
173 Xlib - C Language X Interface
174X Version 11 libX11 1.0.3 XPutImage(3X11)