← Back to branch summary

~ubuntu-branches/ubuntu/gutsy/vnc4/gutsy

« back to all changes in this revision

Viewing changes to unix/xc/doc/man/X11/XCreImage.man

  • Committer: Bazaar Package Importer
  • Author(s): Ola Lundqvist
  • Date: 2006-05-15 20:35:17 UTC
  • mfrom: (1.1.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20060515203517-l4lre1ku942mn26k
Tags: 4.1.1+X4.3.0-10
* Correction of critical security issue. Thanks to Martin Kogler
  <e9925248@student.tuwien.ac.at> that informed me about the issue,
  and provided the patch.
  This flaw was originally found by Steve Wiseman of intelliadmin.com.
* Applied patch from Javier Kohen <jkohen@users.sourceforge.net> that
  inform the user that only 8 first characters of the password will
  actually be used when typing more than 8 characters, closes:
  #355619.

Show diffs side-by-side

added added

removed removed

Lines of Context:
unix/xc/doc/man/X11/XCreImage.man
 
1
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991, 1994, 1996 X Consortium
 
2
.\"
 
3
.\" Permission is hereby granted, free of charge, to any person obtaining
 
4
.\" a copy of this software and associated documentation files (the
 
5
.\" "Software"), to deal in the Software without restriction, including
 
6
.\" without limitation the rights to use, copy, modify, merge, publish,
 
7
.\" distribute, sublicense, and/or sell copies of the Software, and to
 
8
.\" permit persons to whom the Software is furnished to do so, subject to
 
9
.\" the following conditions:
 
10
.\"
 
11
.\" The above copyright notice and this permission notice shall be included
 
12
.\" in all copies or substantial portions of the Software.
 
13
.\"
 
14
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 
15
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 
16
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 
17
.\" IN NO EVENT SHALL THE X CONSORTIUM BE LIABLE FOR ANY CLAIM, DAMAGES OR
 
18
.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 
19
.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 
20
.\" OTHER DEALINGS IN THE SOFTWARE.
 
21
.\"
 
22
.\" Except as contained in this notice, the name of the X Consortium shall
 
23
.\" not be used in advertising or otherwise to promote the sale, use or
 
24
.\" other dealings in this Software without prior written authorization
 
25
.\" from the X Consortium.
 
26
.\"
 
27
.\" Copyright \(co 1985, 1986, 1987, 1988, 1989, 1990, 1991 by
 
28
.\" Digital Equipment Corporation
 
29
.\"
 
30
.\" Portions Copyright \(co 1990, 1991 by
 
31
.\" Tektronix, Inc.
 
32
.\"
 
33
.\" Permission to use, copy, modify and distribute this documentation for
 
34
.\" any purpose and without fee is hereby granted, provided that the above
 
35
.\" copyright notice appears in all copies and that both that copyright notice
 
36
.\" and this permission notice appear in all copies, and that the names of
 
37
.\" Digital and Tektronix not be used in in advertising or publicity pertaining
 
38
.\" to this documentation without specific, written prior permission.
 
39
.\" Digital and Tektronix makes no representations about the suitability
 
40
.\" of this documentation for any purpose.
 
41
.\" It is provided ``as is'' without express or implied warranty.
 
42
.\" 
 
43
.\" $XFree86: xc/doc/man/X11/XCreImage.man,v 1.2 2001/01/27 18:19:57 dawes Exp $
 
44
.\"
 
45
.ds xT X Toolkit Intrinsics \- C Language Interface
 
46
.ds xW Athena X Widgets \- C Language X Toolkit Interface
 
47
.ds xL Xlib \- C Language X Interface
 
48
.ds xC Inter-Client Communication Conventions Manual
 
49
.na
 
50
.de Ds
 
51
.nf
 
52
.\\$1D \\$2 \\$1
 
53
.ft 1
 
54
.\".ps \\n(PS
 
55
.\".if \\n(VS>=40 .vs \\n(VSu
 
56
.\".if \\n(VS<=39 .vs \\n(VSp
 
57
..
 
58
.de De
 
59
.ce 0
 
60
.if \\n(BD .DF
 
61
.nr BD 0
 
62
.in \\n(OIu
 
63
.if \\n(TM .ls 2
 
64
.sp \\n(DDu
 
65
.fi
 
66
..
 
67
.de FD
 
68
.LP
 
69
.KS
 
70
.TA .5i 3i
 
71
.ta .5i 3i
 
72
.nf
 
73
..
 
74
.de FN
 
75
.fi
 
76
.KE
 
77
.LP
 
78
..
 
79
.de IN          \" send an index entry to the stderr
 
80
..
 
81
.de C{
 
82
.KS
 
83
.nf
 
84
.D
 
85
.\"
 
86
.\"     choose appropriate monospace font
 
87
.\"     the imagen conditional, 480,
 
88
.\"     may be changed to L if LB is too
 
89
.\"     heavy for your eyes...
 
90
.\"
 
91
.ie "\\*(.T"480" .ft L
 
92
.el .ie "\\*(.T"300" .ft L
 
93
.el .ie "\\*(.T"202" .ft PO
 
94
.el .ie "\\*(.T"aps" .ft CW
 
95
.el .ft R
 
96
.ps \\n(PS
 
97
.ie \\n(VS>40 .vs \\n(VSu
 
98
.el .vs \\n(VSp
 
99
..
 
100
.de C}
 
101
.DE
 
102
.R
 
103
..
 
104
.de Pn
 
105
.ie t \\$1\fB\^\\$2\^\fR\\$3
 
106
.el \\$1\fI\^\\$2\^\fP\\$3
 
107
..
 
108
.de ZN
 
109
.ie t \fB\^\\$1\^\fR\\$2
 
110
.el \fI\^\\$1\^\fP\\$2
 
111
..
 
112
.de hN
 
113
.ie t <\fB\\$1\fR>\\$2
 
114
.el <\fI\\$1\fP>\\$2
 
115
..
 
116
.de NT
 
117
.ne 7
 
118
.ds NO Note
 
119
.if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 
120
.if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 
121
.ie n .sp
 
122
.el .sp 10p
 
123
.TB
 
124
.ce
 
125
\\*(NO
 
126
.ie n .sp
 
127
.el .sp 5p
 
128
.if '\\$1'C' .ce 99
 
129
.if '\\$2'C' .ce 99
 
130
.in +5n
 
131
.ll -5n
 
132
.R
 
133
..
 
134
.               \" Note End -- doug kraft 3/85
 
135
.de NE
 
136
.ce 0
 
137
.in -5n
 
138
.ll +5n
 
139
.ie n .sp
 
140
.el .sp 10p
 
141
..
 
142
.ny0
 
143
.TH XCreateImage 3X11 __xorgversion__ "XLIB FUNCTIONS"
 
144
.SH NAME
 
145
XInitImage, XCreateImage, XGetPixel, XPutPixel, XSubImage, XAddPixel, XDestroyImage \- image utilities
 
146
.SH SYNTAX
 
147
Status XInitImage\^(\^\fIimage\fP\^)
 
148
.br
 
149
      XImage *\fIimage\fP\^;
 
150
.LP
 
151
XImage *XCreateImage\^(\^\fIdisplay\fP, \fIvisual\fP, \fIdepth\fP, \fIformat\fP, \fIoffset\fP, \fIdata\fP, \fIwidth\fP, \fIheight\fP\^, \fIbitmap_pad\fP, 
 
152
.br
 
153
                        \fIbytes_per_line\fP\^)
 
154
.br
 
155
      Display *\fIdisplay\fP\^;
 
156
.br
 
157
      Visual *\fIvisual\fP\^;
 
158
.br
 
159
      unsigned int \fIdepth\fP\^;
 
160
.br
 
161
      int \fIformat\fP\^;
 
162
.br
 
163
      int \fIoffset\fP\^;
 
164
.br
 
165
      char *\fIdata\fP\^;
 
166
.br
 
167
      unsigned int \fIwidth\fP\^;
 
168
.br
 
169
      unsigned int \fIheight\fP\^;
 
170
.br
 
171
      int \fIbitmap_pad\fP\^;
 
172
.br
 
173
      int \fIbytes_per_line\fP\^;
 
174
.LP
 
175
unsigned long XGetPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP\^)
 
176
.br
 
177
      XImage *\fIximage\fP\^;
 
178
.br
 
179
      int \fIx\fP\^;
 
180
.br
 
181
      int \fIy\fP\^;
 
182
.LP
 
183
XPutPixel\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIpixel\fP\^)
 
184
.br
 
185
      XImage *\fIximage\fP\^;
 
186
.br
 
187
      int \fIx\fP\^;
 
188
.br
 
189
      int \fIy\fP\^;
 
190
.br
 
191
      unsigned long \fIpixel\fP\^;
 
192
.LP
 
193
XImage *XSubImage\^(\^\fIximage\fP, \fIx\fP, \fIy\fP, \fIsubimage_width\fP, \fIsubimage_height\fP\^)
 
194
.br
 
195
      XImage *\fIximage\fP\^;
 
196
.br
 
197
      int \fIx\fP\^;
 
198
.br
 
199
      int \fIy\fP\^;
 
200
.br
 
201
      unsigned int \fIsubimage_width\fP\^;
 
202
.br
 
203
      unsigned int \fIsubimage_height\fP\^;
 
204
.LP
 
205
XAddPixel\^(\^\fIximage\fP, \fIvalue\fP\^)
 
206
.br
 
207
      XImage *\fIximage\fP\^;
 
208
.br
 
209
      long \fIvalue\fP\^;
 
210
.LP
 
211
XDestroyImage\^(\^\fIximage\fP\^)
 
212
.br
 
213
        XImage *\^\fIximage\fP\^; 
 
214
.SH ARGUMENTS
 
215
.IP \fIbitmap_pad\fP 1i
 
216
Specifies the quantum of a scanline (8, 16, or 32).
 
217
In other words, the start of one scanline is separated in client memory from 
 
218
the start of the next scanline by an integer multiple of this many bits.  
 
219
.IP \fIbytes_per_line\fP 1i
 
220
Specifies the number of bytes in the client image between
 
221
the start of one scanline and the start of the next.  
 
222
.IP \fIdata\fP 1i
 
223
Specifies the image data.
 
224
.IP \fIdepth\fP 1i
 
225
Specifies the depth of the image.
 
226
.IP \fIdisplay\fP 1i
 
227
Specifies the connection to the X server.
 
228
.IP \fIformat\fP 1i
 
229
Specifies the format for the image.
 
230
You can pass
 
231
.ZN XYBitmap ,
 
232
.ZN XYPixmap ,
 
233
or 
 
234
.ZN ZPixmap .
 
235
.IP \fIheight\fP 1i
 
236
Specifies the height of the image, in pixels.
 
237
.IP \fIoffset\fP 1i
 
238
Specifies the number of pixels to ignore at the beginning of the scanline.
 
239
.IP \fIpixel\fP 1i
 
240
Specifies the new pixel value.
 
241
.IP \fIsubimage_height\fP 1i
 
242
Specifies the height of the new subimage, in pixels.
 
243
.IP \fIsubimage_width\fP 1i
 
244
Specifies the width of the new subimage, in pixels.
 
245
.IP \fIvalue\fP 1i
 
246
Specifies the constant value that is to be added.
 
247
.IP \fIvisual\fP 1i
 
248
Specifies the
 
249
.ZN Visual
 
250
structure.
 
251
.IP \fIwidth\fP 1i
 
252
Specifies the width of the image, in pixels.
 
253
.IP \fIximage\fP 1i
 
254
Specifies the image.
 
255
.IP \fIx\fP 1i
 
256
.br
 
257
.ns
 
258
.IP \fIy\fP 1i
 
259
Specify the x and y coordinates.
 
260
.SH DESCRIPTION
 
261
The
 
262
.ZN XInitImage
 
263
function initializes the internal image manipulation routines of an
 
264
image structure, based on the values of the various structure members.
 
265
All fields other than the manipulation routines must already be initialized.
 
266
If the bytes_per_line member is zero,
 
267
.ZN XInitImage
 
268
will assume the image data is contiguous in memory and set the
 
269
bytes_per_line member to an appropriate value based on the other
 
270
members; otherwise, the value of bytes_per_line is not changed.
 
271
All of the manipulation routines are initialized to functions
 
272
that other Xlib image manipulation functions need to operate on the
 
273
type of image specified by the rest of the structure.
 
274
.LP
 
275
This function must be called for any image constructed by the client
 
276
before passing it to any other Xlib function.
 
277
Image structures created or returned by Xlib do not need to be
 
278
initialized in this fashion.
 
279
.LP
 
280
This function returns a nonzero status if initialization of the
 
281
structure is successful.  It returns zero if it detected some error
 
282
or inconsistency in the structure, in which case the image is not changed.
 
283
.LP
 
284
The
 
285
.ZN XCreateImage
 
286
function allocates the memory needed for an
 
287
.ZN XImage
 
288
structure for the
 
289
specified display but does not allocate space for the image itself.
 
290
Rather, it initializes the structure byte-order, bit-order, and bitmap-unit
 
291
values from the display and returns a pointer to the 
 
292
.ZN XImage 
 
293
structure.
 
294
The red, green, and blue mask values are defined for Z format images only
 
295
and are derived from the 
 
296
.ZN Visual 
 
297
structure passed in.
 
298
Other values also are passed in.
 
299
The offset permits the rapid displaying of the image without requiring each 
 
300
scanline to be shifted into position.
 
301
If you pass a zero value in bytes_per_line,
 
302
Xlib assumes that the scanlines are contiguous
 
303
in memory and calculates the value of bytes_per_line itself.
 
304
.LP
 
305
Note that when the image is created using
 
306
.ZN XCreateImage ,
 
307
.ZN XGetImage ,
 
308
or
 
309
.ZN XSubImage ,
 
310
the destroy procedure that the 
 
311
.ZN XDestroyImage
 
312
function calls frees both the image structure 
 
313
and the data pointed to by the image structure.
 
314
.LP
 
315
The basic functions used to get a pixel, set a pixel, create a subimage,
 
316
and add a constant value to an image are defined in the image object.
 
317
The functions in this section are really macro invocations of the functions
 
318
in the image object and are defined in
 
319
.hN X11/Xutil.h .
 
320
.LP
 
321
The
 
322
.ZN XGetPixel
 
323
function returns the specified pixel from the named image.
 
324
The pixel value is returned in normalized format (that is,
 
325
the least significant byte of the long is the least significant byte
 
326
of the pixel).
 
327
The image must contain the x and y coordinates.
 
328
.LP
 
329
The
 
330
.ZN XPutPixel
 
331
function overwrites the pixel in the named image with the specified pixel value.
 
332
The input pixel value must be in normalized format
 
333
(that is, the least significant byte of the long is the least significant
 
334
byte of the pixel).
 
335
The image must contain the x and y coordinates.
 
336
.LP
 
337
The
 
338
.ZN XSubImage
 
339
function creates a new image that is a subsection of an existing one.
 
340
It allocates the memory necessary for the new
 
341
.ZN XImage
 
342
structure
 
343
and returns a pointer to the new image.
 
344
The data is copied from the source image,
 
345
and the image must contain the rectangle defined by x, y, subimage_width,
 
346
and subimage_height.
 
347
.LP
 
348
The
 
349
.ZN XAddPixel
 
350
function adds a constant value to every pixel in an image.
 
351
It is useful when you have a base pixel value from allocating
 
352
color resources and need to manipulate the image to that form.
 
353
.LP
 
354
The
 
355
.ZN XDestroyImage
 
356
function deallocates the memory associated with the
 
357
.ZN XImage
 
358
structure.
 
359
.SH "SEE ALSO"
 
360
XPutImage(3X11)
 
361
.br
 
362
\fI\*(xL\fP