sys/man/2/allocimage

   1 .TH ALLOCIMAGE 2
   2 .SH NAME
   3 allocimage, allocimagemix, freeimage, nameimage, namedimage, setalpha, loadimage, cloadimage, unloadimage, readimage, writeimage, bytesperline, wordsperline \- allocating, freeing, reading, writing images
   4 .SH SYNOPSIS
   5 .nf
   6 .PP
   7 .B
   8 #include <u.h>
   9 .B
  10 #include <libc.h>
  11 .B
  12 #include <draw.h>
  13 .PP
  14 .ta \w'\fLImage 'u
  15 .B
  16 Image   *allocimage(Display *d, Rectangle r,
  17 .br
  18 .B
  19         ulong chan, int repl, ulong col)
  20 .PP
  21 .B
  22 Image   *allocimagemix(Display *d, ulong one, ulong three)
  23 .PP
  24 .B
  25 int     freeimage(Image *i)
  26 .PP
  27 .B
  28 int     nameimage(Image *i, char *name, int in)
  29 .PP
  30 .B
  31 Image   *namedimage(Display *d, char *name)
  32 .PP
  33 .B
  34 ulong   setalpha(ulong color, uchar alpha)
  35 .PP
  36 .B
  37 int     loadimage(Image *i, Rectangle r, uchar *data, int ndata)
  38 .PP
  39 .B
  40 int     cloadimage(Image *i, Rectangle r, uchar *data, int ndata)
  41 .PP
  42 .B
  43 int     unloadimage(Image *i, Rectangle r, uchar *data, int ndata)
  44 .PP
  45 .B
  46 Image   *readimage(Display *d, int fd, int dolock)
  47 .PP
  48 .B
  49 int     writeimage(int fd, Image *i, int dolock)
  50 .PP
  51 .B
  52 int     bytesperline(Rectangle r, int d)
  53 .PP
  54 .B
  55 int     wordsperline(Rectangle r, int d)
  56 .PP
  57 .nf
  58 .B
  59 enum
  60 .nf
  61 .ft L
  62 .ta +4n +20
  63 {
  64         DOpaque         = 0xFFFFFFFF,
  65         DTransparent    = 0x00000000,
  66         DBlack          = 0x000000FF,
  67         DWhite          = 0xFFFFFFFF,
  68         DRed            = 0xFF0000FF,
  69         DGreen          = 0x00FF00FF,
  70         DBlue           = 0x0000FFFF,
  71         DCyan           = 0x00FFFFFF,
  72         DMagenta                = 0xFF00FFFF,
  73         DYellow         = 0xFFFF00FF,
  74         DPaleyellow     = 0xFFFFAAFF,
  75         DDarkyellow     = 0xEEEE9EFF,
  76         DDarkgreen      = 0x448844FF,
  77         DPalegreen      = 0xAAFFAAFF,
  78         DMedgreen       = 0x88CC88FF,
  79         DDarkblue       = 0x000055FF,
  80         DPalebluegreen  = 0xAAFFFFFF,
  81         DPaleblue               = 0x0000BBFF,
  82         DBluegreen      = 0x008888FF,
  83         DGreygreen      = 0x55AAAAFF,
  84         DPalegreygreen  = 0x9EEEEEFF,
  85         DYellowgreen    = 0x99994CFF,
  86         DMedblue                = 0x000099FF,
  87         DGreyblue       = 0x005DBBFF,
  88         DPalegreyblue   = 0x4993DDFF,
  89         DPurpleblue     = 0x8888CCFF,
  90
  91         DNotacolor      = 0xFFFFFF00,
  92         DNofill         = DNotacolor,
  93
  94 };
  95 .fi
  96 .SH DESCRIPTION
  97 A new
  98 .B Image
  99 on
 100 .B Display
 101 .B d
 102 is allocated with
 103 .BR allocimage ;
 104 it will have the rectangle, pixel channel format,
 105 replication flag,
 106 and initial fill color
 107 given by its arguments.
 108 Convenient pixel channels like
 109 .BR GREY1 ,
 110 .BR GREY2 ,
 111 .BR CMAP8 ,
 112 .BR RGB16 ,
 113 .BR RGB24 ,
 114 and
 115 .BR RGBA32
 116 are predefined.
 117 All the new image's pixels will have initial value
 118 .IR col .
 119 If
 120 .I col
 121 is
 122 .BR DNofill ,
 123 no initialization is done.
 124 Representative useful values of color are predefined:
 125 .BR DBlack ,
 126 .BR DWhite ,
 127 .BR DRed ,
 128 and so on.
 129 Colors are specified by 32-bit numbers comprising,
 130 from most to least significant byte,
 131 8-bit values for red, green, blue, and alpha.
 132 The values correspond to illumination, so 0 is black and 255 is white.
 133 Similarly, for alpha 0 is transparent and 255 is opaque.
 134 The
 135 .I id
 136 field will have been set to the identifying number used by
 137 .B /dev/draw
 138 (see
 139 .IR draw (3)),
 140 and the
 141 .I cache
 142 field will be zero.
 143 If
 144 .I repl
 145 is true, the clip rectangle is set to a very large region; if false, it is set to
 146 .IR r .
 147 The
 148 .I depth
 149 field will be set to the number of bits per pixel specified
 150 by the channel descriptor
 151 (see
 152 .IR image (6)).
 153 .I Allocimage
 154 returns 0 if the server has run out of image memory.
 155 .PP
 156 .I Allocimagemix
 157 is used to allocate background colors.
 158 On 8-bit color-mapped displays, it
 159 returns a 2×2 replicated image with one pixel colored
 160 the color
 161 .I one
 162 and the other three with
 163 .IR three .
 164 (This simulates a wider range of tones than can be represented by a single pixel
 165 value on a color-mapped display.)
 166 On true color displays, it returns a 1×1 replicated image
 167 whose pixel is the result of mixing the two colors in
 168 a one to three ratio.
 169 .PP
 170 .I Freeimage
 171 frees the resources used by its argument image.
 172 .PP
 173 .I Nameimage
 174 publishes in the server the image
 175 .I i
 176 under the given
 177 .IR name .
 178 If
 179 .I in
 180 is non-zero, the image is published; otherwise
 181 .I i
 182 must be already named
 183 .I name
 184 and it is withdrawn from publication.
 185 .I Namedimage
 186 returns a reference to the image published under the given
 187 .I name
 188 on
 189 .B Display
 190 .IR d .
 191 These routines permit unrelated applications sharing a display to share an image;
 192 for example they provide the mechanism behind
 193 .B getwindow
 194 (see
 195 .IR graphics (2)).
 196 .PP
 197 The RGB values in a color are
 198 .I premultiplied
 199 by the alpha value; for example, a 50% red is
 200 .B 0x7F00007F
 201 not
 202 .BR 0xFF00007F .
 203 The function
 204 .I setalpha
 205 performs the alpha computation on a given
 206 .BR color ,
 207 ignoring its initial alpha value, multiplying the components by the supplied
 208 .BR alpha .
 209 For example, to make a 50% red color value, one could execute
 210 .B setalpha(DRed,
 211 .BR 0x7F) .
 212 .PP
 213 The remaining functions deal with moving groups of pixel
 214 values between image and user space or external files.
 215 There is a fixed format for the exchange and storage of
 216 image data
 217 (see
 218 .IR image (6)).
 219 .PP
 220 .I Unloadimage
 221 reads a rectangle of pixels from image
 222 .I i
 223 into
 224 .IR data ,
 225 whose length is specified by
 226 .IR ndata .
 227 It is an error if
 228 .I ndata
 229 is too small to accommodate the pixels.
 230 .PP
 231 .I Loadimage
 232 replaces the specified rectangle in image
 233 .I i
 234 with the
 235 .I ndata
 236 bytes of
 237 .IR data .
 238 .PP
 239 The pixels are presented one horizontal line at a time,
 240 starting with the top-left pixel of
 241 .IR r .
 242 In the data processed by these routines, each scan line starts with a new byte in the array,
 243 leaving the last byte of the previous line partially empty, if necessary.
 244 Pixels are packed as tightly as possible within
 245 .IR data ,
 246 regardless of the rectangle being extracted.
 247 Bytes are filled from most to least significant bit order,
 248 as the
 249 .I x
 250 coordinate increases, aligned so
 251 .IR x =0
 252 would appear as the leftmost pixel of its byte.
 253 Thus, for
 254 .B depth
 255 1, the pixel at
 256 .I x
 257 offset 165 within the rectangle will be in a
 258 .I data
 259 byte at bit-position
 260 .B 0x04
 261 regardless of the overall
 262 rectangle: 165 mod 8 equals 5, and
 263 .B "0x80\ >>\ 5"
 264 equals
 265 .BR 0x04 .
 266 .PP
 267 .B Cloadimage
 268 does the same as
 269 .IR loadimage ,
 270 but for
 271 .I ndata
 272 bytes of compressed image
 273 .I data
 274 (see
 275 .IR image (6)).
 276 On each call to
 277 .IR cloadimage,
 278 the
 279 .I data
 280 must be at the beginning of a compressed data block, in particular,
 281 it should start with the
 282 .B y
 283 coordinate and data length for the block.
 284 .PP
 285 .IR Loadimage ,
 286 .IR cloadimage ,
 287 and
 288 .I unloadimage
 289 return the number of bytes copied.
 290 .PP
 291 .I Readimage
 292 creates an image from data contained in an external file (see
 293 .IR image (6)
 294 for the file format);
 295 .I fd
 296 is a file descriptor obtained by opening such a file for reading.
 297 The returned image is allocated using
 298 .IR allocimage .
 299 The
 300 .I dolock
 301 flag specifies whether the
 302 .B Display
 303 should be synchronized for multithreaded access; single-threaded
 304 programs can leave it zero.
 305 .PP
 306 .I Writeimage
 307 writes image
 308 .I i
 309 onto file descriptor
 310 .IR fd ,
 311 which should be open for writing.
 312 The format is as described for
 313 .IR readimage .
 314 .PP
 315 .I Readimage
 316 and
 317 .I writeimage
 318 do not close
 319 .IR fd .
 320 .PP
 321 .I Bytesperline
 322 and
 323 .I wordsperline
 324 return the number of bytes or words occupied in memory by one scan line of rectangle
 325 .I r
 326 in an image with
 327 .I d
 328 bits per pixel.
 329 .SH EXAMPLE
 330 To allocate a single-pixel replicated image that may be used to paint a region red,
 331 .EX
 332         red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed);
 333 .EE
 334 .SH SOURCE
 335 .B /sys/src/libdraw
 336 .SH "SEE ALSO"
 337 .IR graphics (2),
 338 .IR draw (2),
 339 .IR draw (3),
 340 .IR image (6)
 341 .SH DIAGNOSTICS
 342 These functions return pointer 0 or integer \-1 on failure, usually due to insufficient
 343 memory.
 344 .PP
 345 May set
 346 .IR errstr .
 347 .SH BUGS
 348 .B Depth
 349 must be a divisor or multiple of 8.