man/XReadBitmapFile.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 .\"
  44 .ds xT X Toolkit Intrinsics \- C Language Interface
  45 .ds xW Athena X Widgets \- C Language X Toolkit Interface
  46 .ds xL Xlib \- C Language X Interface
  47 .ds xC Inter-Client Communication Conventions Manual
  48 .na
  49 .de Ds
  50 .nf
  51 .\\$1D \\$2 \\$1
  52 .ft 1
  53 .\".ps \\n(PS
  54 .\".if \\n(VS>=40 .vs \\n(VSu
  55 .\".if \\n(VS<=39 .vs \\n(VSp
  56 ..
  57 .de De
  58 .ce 0
  59 .if \\n(BD .DF
  60 .nr BD 0
  61 .in \\n(OIu
  62 .if \\n(TM .ls 2
  63 .sp \\n(DDu
  64 .fi
  65 ..
  66 .de FD
  67 .LP
  68 .KS
  69 .TA .5i 3i
  70 .ta .5i 3i
  71 .nf
  72 ..
  73 .de FN
  74 .fi
  75 .KE
  76 .LP
  77 ..
  78 .de IN          \" send an index entry to the stderr
  79 ..
  80 .de C{
  81 .KS
  82 .nf
  83 .D
  84 .\"
  85 .\"     choose appropriate monospace font
  86 .\"     the imagen conditional, 480,
  87 .\"     may be changed to L if LB is too
  88 .\"     heavy for your eyes...
  89 .\"
  90 .ie "\\*(.T"480" .ft L
  91 .el .ie "\\*(.T"300" .ft L
  92 .el .ie "\\*(.T"202" .ft PO
  93 .el .ie "\\*(.T"aps" .ft CW
  94 .el .ft R
  95 .ps \\n(PS
  96 .ie \\n(VS>40 .vs \\n(VSu
  97 .el .vs \\n(VSp
  98 ..
  99 .de C}
 100 .DE
 101 .R
 102 ..
 103 .de Pn
 104 .ie t \\$1\fB\^\\$2\^\fR\\$3
 105 .el \\$1\fI\^\\$2\^\fP\\$3
 106 ..
 107 .de ZN
 108 .ie t \fB\^\\$1\^\fR\\$2
 109 .el \fI\^\\$1\^\fP\\$2
 110 ..
 111 .de hN
 112 .ie t <\fB\\$1\fR>\\$2
 113 .el <\fI\\$1\fP>\\$2
 114 ..
 115 .de NT
 116 .ne 7
 117 .ds NO Note
 118 .if \\n(.$>$1 .if !'\\$2'C' .ds NO \\$2
 119 .if \\n(.$ .if !'\\$1'C' .ds NO \\$1
 120 .ie n .sp
 121 .el .sp 10p
 122 .TB
 123 .ce
 124 \\*(NO
 125 .ie n .sp
 126 .el .sp 5p
 127 .if '\\$1'C' .ce 99
 128 .if '\\$2'C' .ce 99
 129 .in +5n
 130 .ll -5n
 131 .R
 132 ..
 133 .               \" Note End -- doug kraft 3/85
 134 .de NE
 135 .ce 0
 136 .in -5n
 137 .ll +5n
 138 .ie n .sp
 139 .el .sp 10p
 140 ..
 141 .ny0
 142 .TH XReadBitmapFile __libmansuffix__ __xorgversion__ "XLIB FUNCTIONS"
 143 .SH NAME
 144 XReadBitmapFile, XReadBitmapFileData, XWriteBitmapFile, XCreatePixmapFromBitmapData, XCreateBitmapFromData \- manipulate bitmaps
 145 .SH SYNTAX
 146 .HP
 147 int XReadBitmapFile(\^Display *\fIdisplay\fP\^, Drawable \fId\fP\^, char
 148 *\fIfilename\fP\^, unsigned int *\fIwidth_return\fP, unsigned int
 149 *\fIheight_return\fP\^, Pixmap *\fIbitmap_return\fP\^, int
 150 *\fIx_hot_return\fP, int *\fIy_hot_return\fP\^);
 151 .HP
 152 int XReadBitmapFileData(\^char *\fIfilename\fP\^, unsigned int
 153 *\fIwidth_return\fP, unsigned int *\fIheight_return\fP\^, unsigned char
 154 *\fIdata_return\fP\^, int *\fIx_hot_return\fP, int *\fIy_hot_return\fP\^);
 155 .HP
 156 int XWriteBitmapFile(\^Display *\fIdisplay\fP\^, char *\fIfilename\fP\^,
 157 Pixmap \fIbitmap\fP\^, unsigned int \fIwidth\fP, unsigned int \fIheight\fP\^,
 158 int \fIx_hot\fP, int \fIy_hot\fP\^);
 159 .HP
 160 Pixmap XCreatePixmapFromBitmapData\^(\^Display *\fIdisplay\fP\^, Drawable
 161 \fId\fP\^, char *\fIdata\fP\^, unsigned int \fIwidth\fP, unsigned int
 162 \fIheight\fP\^, unsigned long \fIfg\fP, unsigned long \fIbg\fP\^, unsigned int
 163 \fIdepth\fP\^);
 164 .HP
 165 Pixmap XCreateBitmapFromData(\^Display *\fIdisplay\fP\^, Drawable \fId\fP\^,
 166 char *\fIdata\fP\^, unsigned int \fIwidth\fP, unsigned int \fIheight\fP\^);
 167 .SH ARGUMENTS
 168 .IP \fIbitmap\fP 1i
 169 Specifies the bitmap.
 170 .IP \fIbitmap_return\fP 1i
 171 Returns the bitmap that is created.
 172 .ds Dr \ that indicates the screen
 173 .IP \fId\fP 1i
 174 Specifies the drawable\*(Dr.
 175 .IP \fIdata\fP 1i
 176 Specifies the data in bitmap format.
 177 .IP \fIdata\fP 1i
 178 Specifies the location of the bitmap data.
 179 .IP \fIdata_return\fP 1i
 180 Returns the bitmap data.
 181 .IP \fIdepth\fP 1i
 182 Specifies the depth of the pixmap.
 183 .IP \fIdisplay\fP 1i
 184 Specifies the connection to the X server.
 185 .IP \fIfg\fP 1i
 186 .br
 187 .ns
 188 .IP \fIbg\fP 1i
 189 Specify the foreground and background pixel values to use.
 190 .IP \fIfilename\fP 1i
 191 Specifies the file name to use.
 192 The format of the file name is operating-system dependent.
 193 .IP \fIwidth\fP 1i
 194 .br
 195 .ns
 196 .IP \fIheight\fP 1i
 197 Specify the width and height.
 198 .IP \fIwidth_return\fP 1i
 199 .br
 200 .ns
 201 .IP \fIheight_return\fP 1i
 202 Return the width and height values of the read in bitmap file.
 203 .IP \fIx_hot\fP 1i
 204 .br
 205 .ns
 206 .IP \fIy_hot\fP 1i
 207 Specify where to place the hotspot coordinates (or \-1,\-1 if none are present)
 208 in the file.
 209 .IP \fIx_hot_return\fP 1i
 210 .br
 211 .ns
 212 .IP \fIy_hot_return\fP 1i
 213 Return the hotspot coordinates.
 214 .SH DESCRIPTION
 215 The
 216 .ZN XReadBitmapFile
 217 function reads in a file containing a bitmap.
 218 The file is parsed in the encoding of the current locale.
 219 The ability to read other than the standard format
 220 is implementation-dependent.
 221 If the file cannot be opened,
 222 .ZN XReadBitmapFile
 223 returns
 224 .ZN BitmapOpenFailed .
 225 If the file can be opened but does not contain valid bitmap data,
 226 it returns
 227 .ZN BitmapFileInvalid .
 228 If insufficient working storage is allocated,
 229 it returns
 230 .ZN BitmapNoMemory .
 231 If the file is readable and valid,
 232 it returns
 233 .ZN BitmapSuccess .
 234 .LP
 235 .ZN XReadBitmapFile
 236 returns the bitmap's height and width, as read
 237 from the file, to width_return and height_return.
 238 It then creates a pixmap of the appropriate size,
 239 reads the bitmap data from the file into the pixmap,
 240 and assigns the pixmap to the caller's variable bitmap.
 241 The caller must free the bitmap using
 242 .ZN XFreePixmap
 243 when finished.
 244 If \fIname\fP_x_hot and \fIname\fP_y_hot exist,
 245 .ZN XReadBitmapFile
 246 returns them to x_hot_return and y_hot_return;
 247 otherwise, it returns \-1,\-1.
 248 .LP
 249 .ZN XReadBitmapFile
 250 can generate
 251 .ZN BadAlloc
 252 and
 253 .ZN BadDrawable
 254 errors.
 255 .LP
 256 The
 257 .ZN XReadBitmapFileData
 258 function reads in a file containing a bitmap, in the same manner as
 259 .ZN XReadBitmapFile ,
 260 but returns the data directly rather than creating a pixmap in the server.
 261 The bitmap data is returned in data_return; the client must free this
 262 storage when finished with it by calling
 263 .ZN XFree .
 264 The status and other return values are the same as for
 265 .ZN XReadBitmapFile .
 266 .LP
 267 The
 268 .ZN XWriteBitmapFile
 269 function writes a bitmap out to a file in the X Version 11 format.
 270 The name used in the output file is derived from the file name
 271 by deleting the directory prefix.
 272 The file is written in the encoding of the current locale.
 273 If the file cannot be opened for writing,
 274 it returns
 275 .ZN BitmapOpenFailed .
 276 If insufficient memory is allocated,
 277 .ZN XWriteBitmapFile
 278 returns
 279 .ZN BitmapNoMemory ;
 280 otherwise, on no error,
 281 it returns
 282 .ZN BitmapSuccess .
 283 If x_hot and y_hot are not \-1, \-1,
 284 .ZN XWriteBitmapFile
 285 writes them out as the hotspot coordinates for the bitmap.
 286 .LP
 287 .ZN XWriteBitmapFile
 288 can generate
 289 .ZN BadDrawable
 290 and
 291 .ZN BadMatch
 292 errors.
 293 .LP
 294 The
 295 .ZN XCreatePixmapFromBitmapData
 296 function creates a pixmap of the given depth and then does a bitmap-format
 297 .ZN XPutImage
 298 of the data into it.
 299 The depth must be supported by the screen of the specified drawable,
 300 or a
 301 .ZN BadMatch
 302 error results.
 303 .LP
 304 .ZN XCreatePixmapFromBitmapData
 305 can generate
 306 .ZN BadAlloc
 307 and
 308 .ZN BadMatch
 309 errors.
 310 .LP
 311 The
 312 .ZN XCreateBitmapFromData
 313 function allows you to include in your C program (using
 314 .ZN #include )
 315 a bitmap file that was written out by
 316 .ZN XWriteBitmapFile
 317 (X version 11 format only) without reading in the bitmap file.
 318 The following example creates a gray bitmap:
 319 .LP
 320 .Ds 0
 321 \&#include "gray.bitmap"
 322 .sp 6p
 323 Pixmap bitmap;
 324 bitmap = XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height);
 325 .De
 326 .LP
 327 If insufficient working storage was allocated,
 328 .ZN XCreateBitmapFromData
 329 returns
 330 .ZN None .
 331 It is your responsibility to free the
 332 bitmap using
 333 .ZN XFreePixmap
 334 when finished.
 335 .LP
 336 .ZN XCreateBitmapFromData
 337 can generate a
 338 .ZN BadAlloc
 339 error.
 340 .SH DIAGNOSTICS
 341 .TP 1i
 342 .ZN BadAlloc
 343 The server failed to allocate the requested resource or server memory.
 344 .TP 1i
 345 .ZN BadDrawable
 346 A value for a Drawable argument does not name a defined Window or Pixmap.
 347 .TP 1i
 348 .ZN BadMatch
 349 An
 350 .ZN InputOnly
 351 window is used as a Drawable.
 352 .SH "SEE ALSO"
 353 XCreatePixmap(__libmansuffix__),
 354 XPutImage(__libmansuffix__)
 355 .br
 356 \fI\*(xL\fP