MAN page from Other AfterStep-2.2.2-20060804.i386.rpm
asvisual
Section: AfterStep X11 window manager (1)
Updated: AfterStep v.2.2.2
Index NAME
asvisual - abstraction layer on top of X Visuals, focusing on color handlinglibAfterImage/asvisual.h
NAMEasvisual
- Defines abstraction layer on top of X Visuals, as well as several fundamental color datatypes.
SEE ALSO
Structures: ColorPair ASScanline ASVisualFunctions : ASScanline handling: prepare_scanline(), free_scanline() ASVisual initialization : query_screen_visual(), setup_truecolor_visual(), setup_pseudo_visual(), setup_as_colormap(),create_asvisual(), destroy_asvisual() ASVisual encoding/decoding : visual2visual_prop(), visual_prop2visual() ASVisual convenience functions : create_visual_window(), create_visual_pixmap(), create_visual_ximage()Other libAfterImage modules : ascmap.h asfont.h asimage.h asvisual.h blender.h export.h import.h transform.h ximage.h
AUTHOR
Sasha Vasko <sasha at aftercode dot net>
FUNCTION
Alpha channel adds visibility parameter to color value.Alpha channel's value of 0xFF signifies complete visibility, while 0makes pixel completely transparent.
SOURCE
Source :
#define ALPHA_TRANSPARENT 0x00#define ALPHA_SEMI_TRANSPARENT 0x7F#define ALPHA_SOLID 0xFF
NAMEARGB32
- main color datatype
FUNCTION
ARGB32 is fundamental datatype that hold 32bit value corresponding topixels color and transparency value (alpha channel) in ARGBcolorspace. It is encoded as follows :Lowermost 8 bits - Blue channelbits 8 to 15 - Green channelbits 16 to 23 - Red channelbits 24 to 31 - Alpha channel
EXAMPLE
ASTile.1
SOURCE
Source :
typedef CARD32 ARGB32;#define ARGB32_White 0xFFFFFFFF#define ARGB32_Black 0xFF000000/* default background color is #FF000000 : */#define ARGB32_DEFAULT_BACK_COLOR ARGB32_Black#define ARGB32_ALPHA_CHAN 3#define ARGB32_RED_CHAN 2#define ARGB32_GREEN_CHAN 1#define ARGB32_BLUE_CHAN 0#define ARGB32_CHANNELS 4#define MAKE_ARGB32(a,r,g,b) ((( (CARD32)a) <<24)| ((((CARD32)r)&0x00FF)<<16)| ((((CARD32)g)&0x00FF)<<8 )| (( (CARD32)b)&0x00FF))#define MAKE_ARGB32_GREY8(a,l) (((a)<<24)|(((l)&0x00FF)<<16)| (((l)&0x00FF)<<8)|((l)&0x00FF))#define ARGB32_ALPHA8(c) (((c)>>24)&0x00FF)#define ARGB32_RED8(c) (((c)>>16)&0x00FF)#define ARGB32_GREEN8(c) (((c)>>8 )&0x00FF)#define ARGB32_BLUE8(c) ( (c) &0x00FF)#define ARGB32_CHAN8(c,i) (((c)>>((i)<<3))&0x00FF)#define MAKE_ARGB32_CHAN8(v,i) (((v)&0x0000FF)<<((i)<<3))#define ARGB32_ALPHA16(c) ((((c)>>16)&0x00FF00)|0x00FF)#define ARGB32_RED16(c) ((((c)>>8)&0x00FF00)|0x00FF)#define ARGB32_GREEN16(c) (( (c) &0x00FF00)|0x00FF)#define ARGB32_BLUE16(c) ((((c)<<8)&0x00FF00)|0x00FF)#define ARGB32_CHAN16(c,i) ((ARGB32_CHAN8(c,i)<<8)|0x00FF)#define MAKE_ARGB32_CHAN16(v,i) ((((v)&0x00FF00)>>8)<<((i)<<3))
NAMEARGB32_manhattan_distance()
- This function can be used to evaluate closeness of two colors.
SYNOPSIS
long ARGB32_manhattan_distance (long a, long b);
INPUTS
- a,
- b - ARGB32 color values to calculate Manhattan distance in between
RETURN VALUE
returns calculated Manhattan distance.
NAMEIC_RED
- red channelIC_GREEN- green channelIC_BLUE- blue channelIC_ALPHA- alpha channelIC_NUM_CHANNELS- number of supported channels
FUNCTION
Ids of the channels. These are basically synonyms to related ARGB32channel numbers
SOURCE
Source :
typedef enum{ IC_BLUE = ARGB32_BLUE_CHAN , IC_GREEN = ARGB32_GREEN_CHAN, IC_RED = ARGB32_RED_CHAN , IC_ALPHA = ARGB32_ALPHA_CHAN, IC_NUM_CHANNELS = ARGB32_CHANNELS}ColorPart; NAMEColorPair
- convenient structure to hold pair of colors.
SOURCE
Source :
typedef struct ColorPair{ ARGB32 fore; ARGB32 back;}ColorPair; NAMEASScanline
- structure to hold contents of the single scanline.
DESCRIPTION
ASScanline holds data for the single scanline, split into channelswith 32 bits per pixel per channel. All the memory is allocated atonce, and then split in between channels. There are three ways toaccess channel data :1) using blue, green, red, alpha pointers.2) using channels[] array of pointers - convenient in loops4) using xc3, xc2, xc1 pointers. These are different from red, green,blue in the way that xc3 will point to blue when BGR mode is specifiedat the time of creation, otherwise it will point to red channel.Likewise xc1 will point to red in BGR mode and blue otherwise.xc2 always points to green channel's data. This is convenient whilewriting XImages and when channels in source and destination has to bereversed, while reading images from files.Channel data is always aligned by 8 byte boundary allowing forutilization of MMX, floating point and other 64bit registers fortransfer and processing.
SEE ALSO
ASImage
SOURCE
Source :
typedef struct ASScanline{#define SCL_DO_BLUE (0x01<<ARGB32_BLUE_CHAN )#define SCL_DO_GREEN (0x01<<ARGB32_GREEN_CHAN)#define SCL_DO_RED (0x01<<ARGB32_RED_CHAN )#define SCL_DO_ALPHA (0x01<<ARGB32_ALPHA_CHAN)#define SCL_DO_COLOR (SCL_DO_RED|SCL_DO_GREEN|SCL_DO_BLUE)#define SCL_DO_ALL (SCL_DO_RED|SCL_DO_GREEN|SCL_DO_BLUE| SCL_DO_ALPHA) CARD32 flags ; /* combination of the above values */ CARD32 *buffer ; CARD32 *blue, *green, *red, *alpha ; CARD32 *channels[IC_NUM_CHANNELS]; CARD32 *xc3, *xc2, *xc1; /* since some servers require * BGR mode here we store what * goes into what color component * in XImage */ ARGB32 back_color; unsigned int width, shift; unsigned int offset_x ;}ASScanline; NAMEprepare_scanline()
SYNOPSIS
ASScanline *prepare_scanline ( unsigned int width, unsigned int shift, ASScanline *reusable_memory, Bool BGR_mode);
INPUTS
- width
- - width of the scanline.
- shift
- - format of contained data. 0 means - 32bit unshifted 8 means - 24.8bit ( 8 bit left shifted ).
- reusable_memory
- - preallocated object.
- BGR_mode
- - if True will cause xc3 to point to Blue and xc1 to point to red.
DESCRIPTION
This function allocates memory ( if reusable_memory is NULL ) forthe new ASScanline structure. Structures buffers gets allocated tohold scanline data of at least width pixel wide. Buffers are adjustedto start on 8 byte boundary.
NAMEfree_scanline()
SYNOPSIS
void free_scanline ( ASScanline *sl, Bool reusable );
INPUTS
- sl
- - pointer to previously allocated ASScanline structure to be deallocated.
- reusable
- - if true then ASScanline object itself will not be deallocated.
DESCRIPTION
free_scanline() frees all the buffer memory allocated for ASScanline.If reusable is false then object itself in not freed. That is usablefor declaring ASScanline on stack.
NAMEASVisual
- an abstraction layer on top of X Server Visual.
DESCRIPTION
This structure has been introduced in order to compensate for thefact that X may have so many different types of Visuals. It providesshortcuts to most Visual data, compensated for differences in Visuals.For PseudoColor visual it also contains preallocated set of colors.This colormap allows us to write XImages very fast and withoutexhausting available X colors. This colormap consist of 8, 64, or 4096colors and constitutes fraction of colors available in particularcolordepth. This colors are allocated to be evenly spread around RGBspectrum. Thus when converting from internal presentation - all weneed to do is to discard unused bits, and use rest of them bits asan index in our colormap. Opposite conversion is much trickier and weengage into nasty business of having hash table mapping pixel valuesinto colors, or straight table doing same in lower colordepths.Idea is that we do all internal processing in 32bit colordepth, andASVisual provides us with means to convert it to actual X displayformat. Respectively ASVisual has methods to write out XImage linesand read XImage lines.ASVisual creation is a tricky process. Basically first we have to gothrough the list of available Visuals and choose the best suitable.Then based on the type of this Visual we have to setup our datamembers and method hooks. Several functions provided for that : query_screen_visual() - will lookup best suitable visual setup_truecolor_visual() - will setup hooks if visual is TrueColor setup_pseudo_visual() - will setup hooks and data if Visual is PseudoColor. setup_as_colormap() - will preallocate colors for PseudoColor.Alternative to the above is : create_asvisual() - it encapsulates all of the above functionality, and returns completely set up ASVisual object.Since Visual selected for ASVisual may differ from default( we choose the best suitable ), all the window creation functionmust provide colormap and some other parameters, like border colorfor example. Thus we created some convenience functions.These should be used instead of standard Xlib calls : create_visual_window() - to create window create_visual_pixmap() - to create pixmap create_visual_ximage() - to create XImageASVisual could be dealolocated and its resources freed with : destroy_asvisual()
EXAMPLE
asview.c: ASView
SOURCE
Source :
typedef struct ASVisual{ Display *dpy; /* This envvar will be used to determine what X Visual * (in hex) to use. If unset then best possible will * be selected automagically : */#define ASVISUAL_ID_ENVVAR "AFTERIMAGE_VISUAL_ID" XVisualInfo visual_info; /* this things are calculated based on Visual : */ unsigned long rshift, gshift, bshift; unsigned long rbits, gbits, bbits; unsigned long true_depth; /* could be 15 when X reports 16 */ Bool BGR_mode; Bool msb_first; /* we must have colormap so that we can safely create windows * with different visuals even if we are in TrueColor mode : */ Colormap colormap; Bool own_colormap; /* tells us to free colormap when we * done */ unsigned long black_pixel, white_pixel; /* for PseudoColor mode we need some more stuff : */ enum { ACM_None = 0, ACM_3BPP, ACM_6BPP, ACM_12BPP } as_colormap_type ; /* there can only be 64 or 4096 entries * so far ( 6 or 12 bpp) */ unsigned long *as_colormap; /* array of preallocated colors for * PseudoColor mode */ union /* reverse color lookup tables : */ { ARGB32 *xref; struct ASHashTable *hash; }as_colormap_reverse ; /* different useful callbacks : */ CARD32 (*color2pixel_func) ( struct ASVisual *asv, CARD32 encoded_color, unsigned long *pixel); void (*pixel2color_func) ( struct ASVisual *asv, unsigned long pixel, CARD32 *red, CARD32 *green, CARD32 *blue); void (*ximage2scanline_func)( struct ASVisual *asv, XImage *xim, ASScanline *sl, int y, unsigned char *xim_data ); void (*scanline2ximage_func)( struct ASVisual *asv, XImage *xim, ASScanline *sl, int y, unsigned char *xim_data );#define ASGLX_Unavailable 0#define ASGLX_Available (0x01<<0)#define ASGLX_DoubleBuffer (0x01<<1)#define ASGLX_RGBA (0x01<<2)#define ASGLX_UseForImageTx (0x01<<3) ASFlagType glx_support ; /* one of the above flags */ void *glx_scratch_gc_indirect ; /* (GLXContext) */ void *glx_scratch_gc_direct ; /* (GLXContext) */ Window scratch_window;#ifndef X_DISPLAY_MISSING#define ARGB2PIXEL(asv,argb,pixel) (asv)->color2pixel_func((asv),(argb),(pixel))#define GET_SCANLINE(asv,xim,sl,y,xim_data) (asv)->ximage2scanline_func((asv),(xim),(sl),(y),(xim_data))#define PUT_SCANLINE(asv,xim,sl,y,xim_data) (asv)->scanline2ximage_func((asv),(xim),(sl),(y),(xim_data))#else#define ARGB2PIXEL(asv,argb,pixel) do{ break; }while(0)#define GET_SCANLINE(asv,xim,sl,y,xim_data) do{ break; }while(0)#define PUT_SCANLINE(asv,xim,sl,y,xim_data) do{ break; }while(0)#endif}ASVisual; NAMEquery_screen_visual_id()
query_screen_visual()
SYNOPSIS
Bool query_screen_visual_id( ASVisual *asv, Display *dpy, int screen, Window root, int default_depth, VisualID visual_id, Colormap cmap );Bool query_screen_visual( ASVisual *asv, Display *dpy, int screen, Window root, int default_depth );
INPUTS
- asv
- - preallocated ASVisual structure.
- dpy
- - valid pointer to opened X display.
- screen
- - screen number on which to query visuals.
- root
- - root window on that screen.
- default_depth-
- default colordepth of the screen.
- visual_id
- - optional ID of prefered Visual.
- cmap
- - optional colormap to be used.
RETURN VALUE
True on success, False on failureASVisual structure pointed by asv will have the following datamembers set on success :dpy, visual_info, colormap, own_colormap, black_pixel, white_pixel.
DESCRIPTION
query_screen_visual_id() will go though prioritized list of possibleVisuals and attempt to match those to what is available on thespecified screen. If all items from list fail, then it goes aboutquerying default visual.query_screen_visual is identical to query_screen_visual_id withvisual_id and cmap set to 0.Once X Visual has been identified, we create X colormap and allocatewhite and black pixels from it.
NAMEsetup_truecolor_visual()
SYNOPSIS
Bool setup_truecolor_visual( ASVisual *asv );
INPUTS
- asv
- - preallocated ASVisual structure.
RETURN VALUE
True on success, False if visual is not TrueColor.
DESCRIPTION
setup_truecolor_visual() checks if Visual is indeed TrueColor and ifso it goes about querying color masks, deducing real XImagecolordepth, and whether we work in BGR mode. It then goes aboutsetting up correct hooks to X IO functions.
NAMEsetup_pseudo_visual()
SYNOPSIS
void setup_pseudo_visual( ASVisual *asv );
INPUTS
- asv
- - preallocated ASVisual structure.
DESCRIPTION
setup_pseudo_visual() assumes that Visual is PseudoColor. It thentries to decide as to how many colors preallocate, and goes aboutsetting up correct X IO hooks and possibly initialization of reversecolormap in case ASVisual already has colormap preallocated.
NAMEsetup_as_colormap()
SYNOPSIS
void setup_as_colormap( ASVisual *asv );
INPUTS
- asv
- - preallocated ASVisual structure.
DESCRIPTION
That has to be called in order to pre-allocate sufficient number ofcolors. It uses colormap size identification supplied in ASVisualstructure. If colors where preallocated successfully - it will alsocreate reverse lookup colormap.
NAMEcreate_asvisual_for_id()
SYNOPSIS
ASVisual *create_asvisual_for_id( Display *dpy, int screen, int default_depth, VisualID visual_id, Colormap cmap, ASVisual *reusable_memory );
INPUTS
- dpy
- - valid pointer to opened X display.
- screen
- - screen number on which to query visuals.
- root
- - root window on that screen.
- default_depth-
- default colordepth of the screen.
- visual_id
- - ID of X visual to use.
- cmap
- - optional ID of the colormap to be used.
- reusable_memory
- - pointer to preallocated ASVisual structure.
RETURN VALUE
Pointer to ASVisual structure initialized with enough informationto be able to deal with current X Visual.
DESCRIPTION
This function calls all the needed functions in order to setup newASVisual structure for the specified screen and visual. Ifreusable_memory is not null - it will not allocate new ASVisualstructure, but instead will use supplied one. Useful for allocatingASVisual on stack.This particular function will not do any autodetection and will useVisual ID supplied. That is usefull when libAfterImage is used withan app that has its own approach to Visual handling, and since Visualson all Windows, Pixmaps and colormaps must match, there is a need tosynchronise visuals used by an app and libAfterImage.
NAMEcreate_asvisual()
SYNOPSIS
ASVisual *create_asvisual( Display *dpy, int screen, int default_depth, ASVisual *reusable_memory );
INPUTS
- dpy
- - valid pointer to opened X display.
- screen
- - screen number on which to query visuals.
- root
- - root window on that screen.
- default_depth-
- default colordepth of the screen.
- reusable_memory
- - pointer to preallocated ASVisual structure.
RETURN VALUE
Pointer to ASVisual structure initialized with enough informationto be able to deal with current X Visual.
DESCRIPTION
This function calls all the needed functions in order to setup newASVisual structure for the specified screen. If reusable_memory isnot null - it will not allocate new ASVisual structure, but insteadwill use supplied one. Useful for allocating ASVisual on stack.It is different from create_asvisualfor_id() in that it will attemptto autodetect best possible visual for the screen. For example on someSUN Solaris X servers there will be both 8bpp pseudocolor and 24bpptruecolor, and default will be 8bpp. In this scenario libAfterImagewill detect and use 24bpp true color visual, thus producing much betterresults.
NAMEdestroy_asvisual()
SYNOPSIS
void destroy_asvisual( ASVisual *asv, Bool reusable );
INPUTS
- asv
- - valid ASVisual structure.
- reusable
- - if True it will cause function to not free object itself.
DESCRIPTION
Cleanup function. Frees all the memory and deallocates all theresources. If reusable is False it will also free the object, pointedto by asv.
EXAMPLE
asview.c: ASView.2
NAMEvisual2visual_prop()
SYNOPSIS
Bool visual2visual_prop( ASVisual *asv, size_t *size, unsigned long *version, unsigned long **data );
INPUTS
- asv
- - valid ASVisual structure.
RETURN VALUE
size - size of the encoded memory block.version - version of the encodingdata - actual encoded memory blockTrue on success, False on failure
DESCRIPTION
This function will encode ASVisual structure into memory block of32 bit values, suitable for storing in X property.
NAMEvisual_prop2visual()
SYNOPSIS
Bool visual_prop2visual( ASVisual *asv, Display *dpy, int screen, size_t size, unsigned long version, unsigned long *data );
INPUTS
- asv
- - valid ASVisual structure.
- dpy
- - valid pointer to open X display.
- screen
- - screen number.
- size
- - encoded memory block's size.
- version
- - version of encoding.
- data
- - actual encoded memory block.
RETURN VALUE
True on success, False on failure
DESCRIPTION
visual_prop2visual() will read ASVisual data from the memory blockencoded by visual2visual_prop(). It could be used to read data fromX property and convert it into usable information - such as colormap,visual info, etc.Note: setup_truecolor_visual() or setup_pseudo_visual() has to beinvoked in order to complete ASVisual setup.
NAMEcreate_visual_window()
SYNOPSIS
Window create_visual_window( ASVisual *asv, Window parent, int x, int y, unsigned int width, unsigned int height, unsigned int border_width, unsigned int wclass, unsigned long mask, XSetWindowAttributes *attributes );
INPUTS
- asv
- - pointer to the valid ASVisual structure.
- parent
- - Window ID of the parent the window.
- x,
- y - initial position of the new window.
- width,
- height - initial size of the new window.
- border_width
- - initial border width of the new window.
- wclass
- - Window class - InputOnly or InputOutput.
- mask
- - defines what attributes are set.
- attributes
- - different window attributes.
RETURN VALUE
ID of the newly created window on success. None on failure.
DESCRIPTION
create_visual_window() will do sanity checks on passed parameters,it will then add mandatory attributes if needed, and attempt tocreate window for the specified ASVisual.
NAMEcreate_visual_gc()
SYNOPSIS
GC create_visual_gc( ASVisual *asv, Window root, unsigned long mask, XGCValues *gcvalues );
INPUTS
- asv
- - pointer to the valid ASVisual structure.
- root
- - Window ID of the root window of destination screen
- mask,
- gcvalues - values for creation of new GC - see XCreateGC() for details.
RETURN VALUE
New GC created for regular window on success. NULL on failure.
DESCRIPTION
create_visual_gc() will create temporary window for the ASVisualspecific depth and Visual and it will then create GC for such window.Obtained GC should be good to be used for manipulation of windows andPixmaps created for the same ASVisual.
NAMEcreate_visual_pixmap()
SYNOPSIS
Pixmap create_visual_pixmap( ASVisual *asv, Window root, unsigned int width, unsigned int height, unsigned int depth );
INPUTS
- asv
- - pointer to the valid ASVisual structure.
- root
- - Window ID of the root window of destination screen
- width,
- height - size of the pixmap to create.
- depth
- - depth of the pixmap to create. If 0 asv->true_depth will be used.
RETURN VALUE
ID of the newly created pixmap on success. None on failure.
DESCRIPTION
create_visual_pixmap() will perform sanity checks on passedparameters, and attempt to create pixmap for the specified ASVisual,root and depth.
NAMEcreate_visual_ximage()
SYNOPSIS
XImage* create_visual_ximage( ASVisual *asv, unsigned int width, unsigned int height, unsigned int depth );
INPUTS
- asv
- - pointer to the valid ASVisual structure.
- width,
- height - size of the XImage to create.
- depth
- - depth of the XImage to create. If 0 asv->true_depth will be used.
RETURN VALUE
pointer to newly created XImage on success. NULL on failure.
DESCRIPTION
create_visual_ximage() will perform sanity checks on passedparameters, and it will attempt to create XImage of sufficient size,and specified colordepth. It will also setup hooks for XImagedeallocation to be handled by custom function.
Index
- NAME
- NAMEasvisual
- SEE ALSO
- AUTHOR
- FUNCTION
- SOURCE
- NAMEARGB32
- FUNCTION
- EXAMPLE
- SOURCE
- NAMEARGB32_manhattan_distance()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- NAMEIC_RED
- FUNCTION
- SOURCE
- NAMEColorPair
- SOURCE
- NAMEASScanline
- DESCRIPTION
- SEE ALSO
- SOURCE
- NAMEprepare_scanline()
- SYNOPSIS
- INPUTS
- DESCRIPTION
- NAMEfree_scanline()
- SYNOPSIS
- INPUTS
- DESCRIPTION
- NAMEASVisual
- DESCRIPTION
- EXAMPLE
- SOURCE
- NAMEquery_screen_visual_id()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEsetup_truecolor_visual()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEsetup_pseudo_visual()
- SYNOPSIS
- INPUTS
- DESCRIPTION
- NAMEsetup_as_colormap()
- SYNOPSIS
- INPUTS
- DESCRIPTION
- NAMEcreate_asvisual_for_id()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEcreate_asvisual()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEdestroy_asvisual()
- SYNOPSIS
- INPUTS
- DESCRIPTION
- EXAMPLE
- NAMEvisual2visual_prop()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEvisual_prop2visual()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEcreate_visual_window()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEcreate_visual_gc()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEcreate_visual_pixmap()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
- NAMEcreate_visual_ximage()
- SYNOPSIS
- INPUTS
- RETURN VALUE
- DESCRIPTION
This document was created byman2html,using the manual pages.
