allocimage.3 (7311B)
1 .TH ALLOCIMAGE 3 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, int col) 20 .PP 21 .B 22 Image *allocimagemix(Display *d, ulong one, ulong three) 23 .PP 24 .B 25 void 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 and replication flag 106 given by its arguments. 107 Convenient pixel channels like 108 .BR GREY1 , 109 .BR GREY2 , 110 .BR CMAP8 , 111 .BR RGB16 , 112 .BR RGB24 , 113 and 114 .BR RGBA32 115 are predefined. 116 All the new image's pixels will have initial value 117 .IR col . 118 If 119 .I col 120 is 121 .BR DNofill , 122 no initialization is done. 123 Representative useful values of color are predefined: 124 .BR DBlack , 125 .BR DWhite , 126 .BR DRed , 127 and so on. 128 Colors are specified by 32-bit numbers comprising, 129 from most to least significant byte, 130 8-bit values for red, green, blue, and alpha. 131 The values correspond to illumination, so 0 is black and 255 is white. 132 Similarly, for alpha 0 is transparent and 255 is opaque. 133 The 134 .I id 135 field will have been set to the identifying number used by 136 .B /dev/draw 137 (see 138 .MR draw (3) ), 139 and the 140 .I cache 141 field will be zero. 142 If 143 .I repl 144 is true, the clip rectangle is set to a very large region; if false, it is set to 145 .IR r . 146 The 147 .I depth 148 field will be set to the number of bits per pixel specified 149 by the channel descriptor 150 (see 151 .MR image (7) ). 152 .I Allocimage 153 returns 0 if the server has run out of image memory. 154 .PP 155 .I Allocimagemix 156 is used to allocate background colors. 157 On 8-bit color-mapped displays, it 158 returns a 2×2 replicated image with one pixel colored 159 the color 160 .I one 161 and the other three with 162 .IR three . 163 (This simulates a wider range of tones than can be represented by a single pixel 164 value on a color-mapped display.) 165 On true color displays, it returns a 1×1 replicated image 166 whose pixel is the result of mixing the two colors in 167 a one to three ratio. 168 .PP 169 .I Freeimage 170 frees the resources used by its argument image. 171 .PP 172 .I Nameimage 173 publishes in the server the image 174 .I i 175 under the given 176 .IR name . 177 If 178 .I in 179 is non-zero, the image is published; otherwise 180 .I i 181 must be already named 182 .I name 183 and it is withdrawn from publication. 184 .I Namedimage 185 returns a reference to the image published under the given 186 .I name 187 on 188 .B Display 189 .IR d . 190 These routines permit unrelated applications sharing a display to share an image; 191 for example they provide the mechanism behind 192 .B getwindow 193 (see 194 .MR graphics (3) ). 195 .PP 196 The RGB values in a color are 197 .I premultiplied 198 by the alpha value; for example, a 50% red is 199 .B 0x7F00007F 200 not 201 .BR 0xFF00007F . 202 The function 203 .I setalpha 204 performs the alpha computation on a given 205 .BR color , 206 ignoring its initial alpha value, multiplying the components by the supplied 207 .BR alpha . 208 For example, to make a 50% red color value, one could execute 209 .B setalpha(DRed, 210 .BR 0x7F) . 211 .PP 212 The remaining functions deal with moving groups of pixel 213 values between image and user space or external files. 214 There is a fixed format for the exchange and storage of 215 image data 216 (see 217 .MR image (7) ). 218 .PP 219 .I Unloadimage 220 reads a rectangle of pixels from image 221 .I i 222 into 223 .IR data , 224 whose length is specified by 225 .IR ndata . 226 It is an error if 227 .I ndata 228 is too small to accommodate the pixels. 229 .PP 230 .I Loadimage 231 replaces the specified rectangle in image 232 .I i 233 with the 234 .I ndata 235 bytes of 236 .IR data . 237 .PP 238 The pixels are presented one horizontal line at a time, 239 starting with the top-left pixel of 240 .IR r . 241 In the data processed by these routines, each scan line starts with a new byte in the array, 242 leaving the last byte of the previous line partially empty, if necessary. 243 Pixels are packed as tightly as possible within 244 .IR data , 245 regardless of the rectangle being extracted. 246 Bytes are filled from most to least significant bit order, 247 as the 248 .I x 249 coordinate increases, aligned so 250 .IR x =0 251 would appear as the leftmost pixel of its byte. 252 Thus, for 253 .B depth 254 1, the pixel at 255 .I x 256 offset 165 within the rectangle will be in a 257 .I data 258 byte at bit-position 259 .B 0x04 260 regardless of the overall 261 rectangle: 165 mod 8 equals 5, and 262 .B "0x80\ >>\ 5" 263 equals 264 .BR 0x04 . 265 .PP 266 .B Cloadimage 267 does the same as 268 .IR loadimage , 269 but for 270 .I ndata 271 bytes of compressed image 272 .I data 273 (see 274 .MR image (7) ). 275 On each call to 276 .IR cloadimage, 277 the 278 .I data 279 must be at the beginning of a compressed data block, in particular, 280 it should start with the 281 .B y 282 coordinate and data length for the block. 283 .PP 284 .IR Loadimage , 285 .IR cloadimage , 286 and 287 .I unloadimage 288 return the number of bytes copied. 289 .PP 290 .I Readimage 291 creates an image from data contained in an external file (see 292 .MR image (7) 293 for the file format); 294 .I fd 295 is a file descriptor obtained by opening such a file for reading. 296 The returned image is allocated using 297 .IR allocimage . 298 The 299 .I dolock 300 flag specifies whether the 301 .B Display 302 should be synchronized for multithreaded access; single-threaded 303 programs can leave it zero. 304 .PP 305 .I Writeimage 306 writes image 307 .I i 308 onto file descriptor 309 .IR fd , 310 which should be open for writing. 311 The format is as described for 312 .IR readimage . 313 .PP 314 .I Readimage 315 and 316 .I writeimage 317 do not close 318 .IR fd . 319 .PP 320 .I Bytesperline 321 and 322 .I wordsperline 323 return the number of bytes or words occupied in memory by one scan line of rectangle 324 .I r 325 in an image with 326 .I d 327 bits per pixel. 328 .SH EXAMPLE 329 To allocate a single-pixel replicated image that may be used to paint a region red, 330 .EX 331 red = allocimage(display, Rect(0, 0, 1, 1), RGB24, 1, DRed); 332 .EE 333 .SH SOURCE 334 .B \*9/src/libdraw 335 .SH "SEE ALSO" 336 .MR graphics (3) , 337 .MR draw (3) , 338 .MR draw (3) , 339 .MR image (7) 340 .SH DIAGNOSTICS 341 These functions return pointer 0 or integer \-1 on failure, usually due to insufficient 342 memory. 343 .PP 344 May set 345 .IR errstr . 346 .SH BUGS 347 .B Depth 348 must be a divisor or multiple of 8.