1asvisual(1) AfterStep X11 window manager asvisual(1)
2
6 asvisual - abstraction layer on top of X Visuals, focusing on color
7 handling libAfterImage/asvisual.h
8
10 - Defines abstraction layer on top of X Visuals, as well as several
11 fundamental color datatypes.
12
15 Structures:
16 ColorPair
17 ASScanline
18 ASVisual
19 Functions :
21 ASScanline handling:
22 prepare_scanline(), free_scanline()
23 ASVisual initialization :
25 query_screen_visual(), setup_truecolor_visual(),
26 setup_pseudo_visual(), setup_as_colormap(),create_asvisual(),
27 destroy_asvisual()
28 ASVisual encoding/decoding :
30 visual2visual_prop(), visual_prop2visual()
31 ASVisual convenience functions :
33 create_visual_window(), create_visual_pixmap(),
34 create_visual_ximage()
35 Other libAfterImage modules :
37 ascmap.h asfont.h asimage.h asvisual.h blender.h export.h
38 import.h transform.h ximage.h
39
41 Sasha Vasko <sasha at aftercode dot net>
42
44 Alpha channel adds visibility parameter to color value.
45 Alpha channel's value of 0xFF signifies complete visibility, while 0
46 makes pixel completely transparent.
47
49 Source :
50 #define ALPHA_TRANSPARENT 0x00
51 #define ALPHA_SEMI_TRANSPARENT 0x7F
52 #define ALPHA_SOLID 0xFF
53
55 - main color datatype
56
59 ARGB32 is fundamental datatype that hold 32bit value corresponding to
60 pixels color and transparency value (alpha channel) in ARGB
61 colorspace. It is encoded as follows :
62 Lowermost 8 bits - Blue channel
63 bits 8 to 15 - Green channel
64 bits 16 to 23 - Red channel
65 bits 24 to 31 - Alpha channel
66
68 ASTile.1
69
71 Source :
72 typedef CARD32 ARGB32;
73 #define ARGB32_White 0xFFFFFFFF
74 #define ARGB32_Black 0xFF000000
75 /* default background color is #FF000000 : */
76 #define ARGB32_DEFAULT_BACK_COLOR ARGB32_Black
77 #define ARGB32_ALPHA_CHAN 3
79 #define ARGB32_RED_CHAN 2
80 #define ARGB32_GREEN_CHAN 1
81 #define ARGB32_BLUE_CHAN 0
82 #define ARGB32_CHANNELS 4
83 #define MAKE_ARGB32(a,r,g,b) ((( (CARD32)a) <<24)| ((((CARD32)r)&0x00FF)<<16)| ((((CARD32)g)&0x00FF)<<8 )| (( (CARD32)b)&0x00FF))
85 #define MAKE_ARGB32_GREY8(a,l) (((a)<<24)|(((l)&0x00FF)<<16)| (((l)&0x00FF)<<8)|((l)&0x00FF))
87 #define ARGB32_ALPHA8(c) (((c)>>24)&0x00FF)
88 #define ARGB32_RED8(c) (((c)>>16)&0x00FF)
89 #define ARGB32_GREEN8(c) (((c)>>8 )&0x00FF)
90 #define ARGB32_BLUE8(c) ( (c) &0x00FF)
91 #define ARGB32_CHAN8(c,i) (((c)>>((i)<<3))&0x00FF)
92 #define MAKE_ARGB32_CHAN8(v,i) (((v)&0x0000FF)<<((i)<<3))
93 #define ARGB32_ALPHA16(c) ((((c)>>16)&0x00FF00)|0x00FF)
95 #define ARGB32_RED16(c) ((((c)>>8)&0x00FF00)|0x00FF)
96 #define ARGB32_GREEN16(c) (( (c) &0x00FF00)|0x00FF)
97 #define ARGB32_BLUE16(c) ((((c)<<8)&0x00FF00)|0x00FF)
98 #define ARGB32_CHAN16(c,i) ((ARGB32_CHAN8(c,i)<<8)|0x00FF)
99 #define MAKE_ARGB32_CHAN16(v,i) ((((v)&0x00FF00)>>8)<<((i)<<3))
100
102 - This function can be used to evaluate closeness of two colors.
103
106 long ARGB32_manhattan_distance (long a, long b);
107
109 a, b - ARGB32 color values to calculate Manhattan distance in
110 between
111
114 returns calculated Manhattan distance.
115
117 - red channel IC_GREEN - green channel IC_BLUE - blue channel IC_ALPHA
118 - alpha channel IC_NUM_CHANNELS - number of supported channels
119
122 Ids of the channels. These are basically synonyms to related ARGB32
123 channel numbers
124
126 Source :
127 typedef enum
128 {
129 IC_BLUE = ARGB32_BLUE_CHAN ,
130 IC_GREEN = ARGB32_GREEN_CHAN,
131 IC_RED = ARGB32_RED_CHAN ,
132 IC_ALPHA = ARGB32_ALPHA_CHAN,
133 IC_NUM_CHANNELS = ARGB32_CHANNELS
134 }
135 ColorPart;
136
138 - convenient structure to hold pair of colors.
139
142 Source :
143 typedef struct ColorPair
144 {
145 ARGB32 fore;
146 ARGB32 back;
147 }ColorPair;
148
150 - structure to hold contents of the single scanline.
151
154 ASScanline holds data for the single scanline, split into channels
155 with 32 bits per pixel per channel. All the memory is allocated at
156 once, and then split in between channels. There are three ways to
157 access channel data :
158 1) using blue, green, red, alpha pointers.
159 2) using channels[] array of pointers - convenient in loops
160 4) using xc3, xc2, xc1 pointers. These are different from red, green,
161 blue in the way that xc3 will point to blue when BGR mode is specified
162 at the time of creation, otherwise it will point to red channel.
163 Likewise xc1 will point to red in BGR mode and blue otherwise.
164 xc2 always points to green channel's data. This is convenient while
165 writing XImages and when channels in source and destination has to be
166 reversed, while reading images from files.
167 Channel data is always aligned by 8 byte boundary allowing for
168 utilization of MMX, floating point and other 64bit registers for
169 transfer and processing.
170
172 ASImage
173
175 Source :
176 typedef struct ASScanline
177 {
178 #define SCL_DO_BLUE (0x01<<ARGB32_BLUE_CHAN )
179 #define SCL_DO_GREEN (0x01<<ARGB32_GREEN_CHAN)
180 #define SCL_DO_RED (0x01<<ARGB32_RED_CHAN )
181 #define SCL_DO_ALPHA (0x01<<ARGB32_ALPHA_CHAN)
182 #define SCL_DO_COLOR (SCL_DO_RED|SCL_DO_GREEN|SCL_DO_BLUE)
183 #define SCL_DO_ALL (SCL_DO_RED|SCL_DO_GREEN|SCL_DO_BLUE| SCL_DO_ALPHA)
184 CARD32 flags ; /* combination of the above values */
185 CARD32 *buffer ;
186 CARD32 *blue, *green, *red, *alpha ;
187 CARD32 *channels[IC_NUM_CHANNELS];
188 CARD32 *xc3, *xc2, *xc1; /* since some servers require
189 * BGR mode here we store what
190 * goes into what color component
191 * in XImage */
192 ARGB32 back_color;
193 unsigned int width, shift;
194 unsigned int offset_x ;
195 }ASScanline;
196
199 ASScanline *prepare_scanline ( unsigned int width,
200 unsigned int shift,
201 ASScanline *reusable_memory,
202 Bool BGR_mode);
203
205 width - width of the scanline.
206 shift - format of contained data. 0 means - 32bit unshifted 8 means -
208 24.8bit ( 8 bit left shifted ).
209 reusable_memory
211 - preallocated object.
212 BGR_mode
214 - if True will cause xc3 to point to Blue and xc1 to point to
215 red.
216
219 This function allocates memory ( if reusable_memory is NULL ) for
220 the new ASScanline structure. Structures buffers gets allocated to
221 hold scanline data of at least width pixel wide. Buffers are adjusted
222 to start on 8 byte boundary.
223
226 void free_scanline ( ASScanline *sl, Bool reusable );
227
229 sl - pointer to previously allocated ASScanline structure to be
230 deallocated.
231 reusable
233 - if true then ASScanline object itself will not be deallocated.
234
237 free_scanline() frees all the buffer memory allocated for ASScanline.
238 If reusable is false then object itself in not freed. That is usable
239 for declaring ASScanline on stack.
240
242 - an abstraction layer on top of X Server Visual.
243
246 This structure has been introduced in order to compensate for the
247 fact that X may have so many different types of Visuals. It provides
248 shortcuts to most Visual data, compensated for differences in Visuals.
249 For PseudoColor visual it also contains preallocated set of colors.
250 This colormap allows us to write XImages very fast and without
251 exhausting available X colors. This colormap consist of 8, 64, or 4096
252 colors and constitutes fraction of colors available in particular
253 colordepth. This colors are allocated to be evenly spread around RGB
254 spectrum. Thus when converting from internal presentation - all we
255 need to do is to discard unused bits, and use rest of them bits as
256 an index in our colormap. Opposite conversion is much trickier and we
257 engage into nasty business of having hash table mapping pixel values
258 into colors, or straight table doing same in lower colordepths.
259 Idea is that we do all internal processing in 32bit colordepth, and
260 ASVisual provides us with means to convert it to actual X display
261 format. Respectively ASVisual has methods to write out XImage lines
262 and read XImage lines.
263 ASVisual creation is a tricky process. Basically first we have to go
264 through the list of available Visuals and choose the best suitable.
265 Then based on the type of this Visual we have to setup our data
266 members and method hooks. Several functions provided for that :
267 query_screen_visual() - will lookup best suitable visual
268 setup_truecolor_visual() - will setup hooks if visual is TrueColor
269 setup_pseudo_visual() - will setup hooks and data if Visual is
270 PseudoColor.
271 setup_as_colormap() - will preallocate colors for PseudoColor.
272 Alternative to the above is :
273 create_asvisual() - it encapsulates all of the above
274 functionality, and returns completely set
275 up ASVisual object.
276 Since Visual selected for ASVisual may differ from default
277 ( we choose the best suitable ), all the window creation function
278 must provide colormap and some other parameters, like border color
279 for example. Thus we created some convenience functions.
280 These should be used instead of standard Xlib calls :
281 create_visual_window() - to create window
282 create_visual_pixmap() - to create pixmap
283 create_visual_ximage() - to create XImage
284 ASVisual could be dealolocated and its resources freed with :
285 destroy_asvisual()
286
288 asview.c: ASView
289
291 Source :
292 typedef struct ASVisual
293 {
294 Display *dpy;
295 /* This envvar will be used to determine what X Visual
297 * (in hex) to use. If unset then best possible will
298 * be selected automagically : */
299 #define ASVISUAL_ID_ENVVAR "AFTERIMAGE_VISUAL_ID"
300 XVisualInfo visual_info;
302 /* this things are calculated based on Visual : */
303 unsigned long rshift, gshift, bshift;
304 unsigned long rbits, gbits, bbits;
305 unsigned long true_depth; /* could be 15 when X reports 16 */
306 Bool BGR_mode;
307 Bool msb_first;
308 /* we must have colormap so that we can safely create windows
309 * with different visuals even if we are in TrueColor mode : */
310 Colormap colormap;
311 Bool own_colormap; /* tells us to free colormap when we
312 * done */
313 unsigned long black_pixel, white_pixel;
314 /* for PseudoColor mode we need some more stuff : */
315 enum {
316 ACM_None = 0,
317 ACM_3BPP,
318 ACM_6BPP,
319 ACM_12BPP
320 } as_colormap_type ; /* there can only be 64 or 4096 entries
321 * so far ( 6 or 12 bpp) */
322 unsigned long *as_colormap; /* array of preallocated colors for
323 * PseudoColor mode */
324 union /* reverse color lookup tables : */
325 {
326 ARGB32 *xref;
327 struct ASHashTable *hash;
328 }as_colormap_reverse ;
329 /* different useful callbacks : */
331 CARD32 (*color2pixel_func) ( struct ASVisual *asv,
332 CARD32 encoded_color,
333 unsigned long *pixel);
334 void (*pixel2color_func) ( struct ASVisual *asv,
335 unsigned long pixel,
336 CARD32 *red, CARD32 *green,
337 CARD32 *blue);
338 void (*ximage2scanline_func)( struct ASVisual *asv,
339 XImage *xim,
340 ASScanline *sl, int y,
341 unsigned char *xim_data );
342 void (*scanline2ximage_func)( struct ASVisual *asv,
343 XImage *xim,
344 ASScanline *sl, int y,
345 unsigned char *xim_data );
346 #define ASGLX_Unavailable 0
348 #define ASGLX_Available (0x01<<0)
349 #define ASGLX_DoubleBuffer (0x01<<1)
350 #define ASGLX_RGBA (0x01<<2)
351 #define ASGLX_UseForImageTx (0x01<<3)
352 ASFlagType glx_support ; /* one of the above flags */
353 void *glx_scratch_gc_indirect ; /* (GLXContext) */
355 void *glx_scratch_gc_direct ; /* (GLXContext) */
356 Window scratch_window;
358 #ifndef X_DISPLAY_MISSING
360 #define ARGB2PIXEL(asv,argb,pixel) (asv)->color2pixel_func((asv),(argb),(pixel))
361 #define GET_SCANLINE(asv,xim,sl,y,xim_data) (asv)->ximage2scanline_func((asv),(xim),(sl),(y),(xim_data))
362 #define PUT_SCANLINE(asv,xim,sl,y,xim_data) (asv)->scanline2ximage_func((asv),(xim),(sl),(y),(xim_data))
363 #else
364 #define ARGB2PIXEL(asv,argb,pixel) do{ break; }while(0)
365 #define GET_SCANLINE(asv,xim,sl,y,xim_data) do{ break; }while(0)
366 #define PUT_SCANLINE(asv,xim,sl,y,xim_data) do{ break; }while(0)
367 #endif
368 }ASVisual;
369
371 query_screen_visual()
372
376 Bool query_screen_visual_id( ASVisual *asv, Display *dpy, int screen,
377 Window root, int default_depth,
378 VisualID visual_id, Colormap cmap );
379 Bool query_screen_visual( ASVisual *asv, Display *dpy, int screen,
380 Window root, int default_depth );
381
383 asv - preallocated ASVisual structure.
384 dpy - valid pointer to opened X display.
386 screen - screen number on which to query visuals.
388 root - root window on that screen.
390 default_depth-
392 default colordepth of the screen.
393 visual_id
395 - optional ID of prefered Visual.
396 cmap - optional colormap to be used.
398
401 True on success, False on failure
402 ASVisual structure pointed by asv will have the following data
403 members set on success :
404 dpy, visual_info, colormap, own_colormap, black_pixel, white_pixel.
405
407 query_screen_visual_id() will go though prioritized list of possible
408 Visuals and attempt to match those to what is available on the
409 specified screen. If all items from list fail, then it goes about
410 querying default visual.
411 query_screen_visual is identical to query_screen_visual_id with
412 visual_id and cmap set to 0.
413 Once X Visual has been identified, we create X colormap and allocate
414 white and black pixels from it.
415
418 Bool setup_truecolor_visual( ASVisual *asv );
419
421 asv - preallocated ASVisual structure.
422
425 True on success, False if visual is not TrueColor.
426
428 setup_truecolor_visual() checks if Visual is indeed TrueColor and if
429 so it goes about querying color masks, deducing real XImage
430 colordepth, and whether we work in BGR mode. It then goes about
431 setting up correct hooks to X IO functions.
432
435 void setup_pseudo_visual( ASVisual *asv );
436
438 asv - preallocated ASVisual structure.
439
442 setup_pseudo_visual() assumes that Visual is PseudoColor. It then
443 tries to decide as to how many colors preallocate, and goes about
444 setting up correct X IO hooks and possibly initialization of reverse
445 colormap in case ASVisual already has colormap preallocated.
446
449 void setup_as_colormap( ASVisual *asv );
450
452 asv - preallocated ASVisual structure.
453
456 That has to be called in order to pre-allocate sufficient number of
457 colors. It uses colormap size identification supplied in ASVisual
458 structure. If colors where preallocated successfully - it will also
459 create reverse lookup colormap.
460
463 ASVisual *create_asvisual_for_id( Display *dpy, int screen,
464 int default_depth,
465 VisualID visual_id, Colormap cmap,
466 ASVisual *reusable_memory );
467
469 dpy - valid pointer to opened X display.
470 screen - screen number on which to query visuals.
472 root - root window on that screen.
474 default_depth-
476 default colordepth of the screen.
477 visual_id
479 - ID of X visual to use.
480 cmap - optional ID of the colormap to be used.
482 reusable_memory
484 - pointer to preallocated ASVisual structure.
485
488 Pointer to ASVisual structure initialized with enough information
489 to be able to deal with current X Visual.
490
492 This function calls all the needed functions in order to setup new
493 ASVisual structure for the specified screen and visual. If
494 reusable_memory is not null - it will not allocate new ASVisual
495 structure, but instead will use supplied one. Useful for allocating
496 ASVisual on stack.
497 This particular function will not do any autodetection and will use
498 Visual ID supplied. That is usefull when libAfterImage is used with
499 an app that has its own approach to Visual handling, and since Visuals
500 on all Windows, Pixmaps and colormaps must match, there is a need to
501 synchronise visuals used by an app and libAfterImage.
502
505 ASVisual *create_asvisual( Display *dpy, int screen,
506 int default_depth,
507 ASVisual *reusable_memory );
508
510 dpy - valid pointer to opened X display.
511 screen - screen number on which to query visuals.
513 root - root window on that screen.
515 default_depth-
517 default colordepth of the screen.
518 reusable_memory
520 - pointer to preallocated ASVisual structure.
521
524 Pointer to ASVisual structure initialized with enough information
525 to be able to deal with current X Visual.
526
528 This function calls all the needed functions in order to setup new
529 ASVisual structure for the specified screen. If reusable_memory is
530 not null - it will not allocate new ASVisual structure, but instead
531 will use supplied one. Useful for allocating ASVisual on stack.
532 It is different from create_asvisualfor_id() in that it will attempt
533 to autodetect best possible visual for the screen. For example on some
534 SUN Solaris X servers there will be both 8bpp pseudocolor and 24bpp
535 truecolor, and default will be 8bpp. In this scenario libAfterImage
536 will detect and use 24bpp true color visual, thus producing much better
537 results.
538
541 void destroy_asvisual( ASVisual *asv, Bool reusable );
542
544 asv - valid ASVisual structure.
545 reusable
547 - if True it will cause function to not free object itself.
548
551 Cleanup function. Frees all the memory and deallocates all the
552 resources. If reusable is False it will also free the object, pointed
553 to by asv.
554
556 asview.c: ASView.2
557
560 Bool visual2visual_prop( ASVisual *asv, size_t *size,
561 unsigned long *version, unsigned long **data );
562
564 asv - valid ASVisual structure.
565
568 size - size of the encoded memory block.
569 version - version of the encoding
570 data - actual encoded memory block
571 True on success, False on failure
572
574 This function will encode ASVisual structure into memory block of
575 32 bit values, suitable for storing in X property.
576
579 Bool visual_prop2visual( ASVisual *asv, Display *dpy, int screen,
580 size_t size,
581 unsigned long version, unsigned long *data );
582
584 asv - valid ASVisual structure.
585 dpy - valid pointer to open X display.
587 screen - screen number.
589 size - encoded memory block's size.
591 version
593 - version of encoding.
594 data - actual encoded memory block.
596
599 True on success, False on failure
600
602 visual_prop2visual() will read ASVisual data from the memory block
603 encoded by visual2visual_prop(). It could be used to read data from
604 X property and convert it into usable information - such as colormap,
605 visual info, etc.
606 Note: setup_truecolor_visual() or setup_pseudo_visual() has to be
607 invoked in order to complete ASVisual setup.
608
611 Window create_visual_window( ASVisual *asv, Window parent,
612 int x, int y,
613 unsigned int width, unsigned int height,
614 unsigned int border_width,
615 unsigned int wclass,
616 unsigned long mask,
617 XSetWindowAttributes *attributes );
618
620 asv - pointer to the valid ASVisual structure.
621 parent - Window ID of the parent the window.
623 x, y - initial position of the new window.
625 width, height - initial size of the new window.
627 border_width
629 - initial border width of the new window.
630 wclass - Window class - InputOnly or InputOutput.
632 mask - defines what attributes are set.
634 attributes
636 - different window attributes.
637
640 ID of the newly created window on success. None on failure.
641
643 create_visual_window() will do sanity checks on passed parameters,
644 it will then add mandatory attributes if needed, and attempt to
645 create window for the specified ASVisual.
646
649 GC create_visual_gc( ASVisual *asv, Window root,
650 unsigned long mask, XGCValues *gcvalues );
651
653 asv - pointer to the valid ASVisual structure.
654 root - Window ID of the root window of destination screen
656 mask, gcvalues - values for creation of new GC - see XCreateGC() for
658 details.
659
662 New GC created for regular window on success. NULL on failure.
663
665 create_visual_gc() will create temporary window for the ASVisual
666 specific depth and Visual and it will then create GC for such window.
667 Obtained GC should be good to be used for manipulation of windows and
668 Pixmaps created for the same ASVisual.
669
672 Pixmap create_visual_pixmap( ASVisual *asv, Window root,
673 unsigned int width, unsigned int height,
674 unsigned int depth );
675
677 asv - pointer to the valid ASVisual structure.
678 root - Window ID of the root window of destination screen
680 width, height - size of the pixmap to create.
682 depth - depth of the pixmap to create. If 0 asv->true_depth will be
684 used.
685
688 ID of the newly created pixmap on success. None on failure.
689
691 create_visual_pixmap() will perform sanity checks on passed
692 parameters, and attempt to create pixmap for the specified ASVisual,
693 root and depth.
694
697 XImage* create_visual_ximage( ASVisual *asv,
698 unsigned int width, unsigned int height,
699 unsigned int depth );
700
702 asv - pointer to the valid ASVisual structure.
703 width, height - size of the XImage to create.
705 depth - depth of the XImage to create. If 0 asv->true_depth will be
707 used.
708
711 pointer to newly created XImage on success. NULL on failure.
712
714 create_visual_ximage() will perform sanity checks on passed
715 parameters, and it will attempt to create XImage of sufficient size,
716 and specified colordepth. It will also setup hooks for XImage
717 deallocation to be handled by custom function.
7183rd Berkeley Distribution AfterStep v.2.2.6 asvisual(1)