Conference bulova::decw_jan-89_to_nov-90

Ken,

The font stuff is the easiest.  You should use XListFontsWithInfo to determine
which fonts are available that satisfy your requirements.  See note 117.3
in CLT::VAXNOTES_V20_IFT for a good description of font naming.  In order to
make this work, determine a set of attributes which are required for the font
to be used.  Set these values in the font name.  Upon obtaining the list of
fonts which qualify check through for attributes which are desirable but not
required.  That way if the specific font you want is available everything is
great.  If not, you can find the one closest to it according to your own
requirements.

The color operation is actually similar.  What you should do is use
XGetVisualInfo to obtain the list of visuals available on the display.
Next you examine the visuals in the list to determine which is "best".

Assuming that you have obtained a PseudoColor, DirectColor or GreyScale visual,
then you can use XCreateColor and XSetWindowColorMap to get a private colormap
for your client.  You can then XAllocColors or XAllocColorCells (depends on
visual) to allocate the writable colors.  Using the WM_COLORMAP_WINDOWS
property on the toplevel window(s) will tell the window manager to install
your colormap when your window has focus.

If the best you can get is a TrueColor or StaticGrey visual, then you can not
write the colormap.  In that case what you will do is to find the colors that
best match the one you want among the colors in the colormap.  It saves you
some trouble but may give you some limitations.

On the Firefox, there are 2 visuals supported.  There is an 8 plane PseudoColor
and a 24 plane TrueColor (this is the default).  It is application dependent
which is better.  If all of the colors you need (or ones sufficiently close)
are available in the TrueColor visual then it is likely to be better.

In all cases the server implementation may reserve a small number of colors
from the colormap for cursors and the like.  This allows you to have 2**n -
m colors.  (n is the number of planes, m is the number of reserved colors).

The above approaches always draw their information from the server.  So there
should not be any problem running remotely.  See the DECpress Xlib book and
the ICCCM for more details on the above routines and properties.

Dick

Xlib
	6.5.2 for font listing
	3.1 for a general discussion of visuals
	5.1.2 for allocating colors
	10.8 for visual info
ICCCM
	4.1.8 for colormap usage

The X WINDOW SYSTEM book from Digital Press by Scheifler, Gettys, and Newman has
an excellent explanation of how color works in X Windows.

If you are using the DECwindows Toolkit (as opposed to simply raw Xlib), then
you are stuck with the default visual.  Currently this is only an issue on the
Firefox (VAXstation 3520/3540), where the default visual is TrueColor.  If you
want to use the 8-plane PseudoColor visual instead of the TrueColor visual, you
are out of luck if you're using the Toolkit.

Once you've selected a visual, your color handling strategy has to be based on
the visual type:

1 plane StaticGray - this is black and white.  You can use BlackPixelOfScreen()
		and WhitePixelOfScreen() or XAllocColor() to obtain the correct
		pixel value to use.

4 plane/8 plane GrayScale - you can only allocate various shades of gray, since
		the system has a monochrome monitor.  You can opt either for
		sharing the default colormap or allocating your own (but then
		you may cause false gray shades in other applications)

4 plane/8 plane PseudoColor - you can allocate colors, up to 14 for a 4 plane
		and 254 for a 8 plane system (note that the cursor occupies 2
		colormap entries for its colors).  Once again, you can either
		share the default colormap or allocate your own.

24 plane TrueColor - You use XAllocColor() to get the pixel value to use for
		the color you want.  The system uses 8 bits each for red, green,
		and blue, so you can theoretically have 16 million different
		colors displayed simultaneously.  You don't have to worry about
		bashing other applications's colors.

The GrayScale and PseudoColor cases are the most interesting.  The options are
to share the default colormap with other applications or to create your own
colormap.

Sharing the default colormap - Use XAllocColorCells() to grab the number of
colormap entries you need.  If you want to grab as many as you can out of the
ones that are free, you can use a loop something like this:

	for (i = 256; i > 1; i--)
	    if (XAllocColorCells(disp, cmap, 0, &planes, 0, &pixels, i))
		{
		n_allocated = i;
		break;
		}

This will try to get 256 colormap entries, then 255, then 254, etc., stopping
either when the allocation succeeds or when it couldn't get even 2 colors.  The
array pixels will contain the pixel values to use for the colormap entries that
were allocated.  If you use this technique to get your pixel values, you will
not bash any other application's colors.

To use your own colormap, call XCreateColormap to create it.  To allocate
colors out of it, either use the AllocAll option or XAllocColorCells().  When
using your own colormap, you can get as many entries as you want (up to the
limitation of the hardware), but when your private colormap is installed, other
windows may go false colors.

Note that the XUI Toolkit usually uses the default colormap, so installing
your own colormap may cause widgets and window decorations to go false colors.
It's possible to get widgets to use your colormap instead of the default, but
the programming is tedious and tricky.  I haven't had good luck with it.

--PSW

    Also a book by Oliver Jones is very good. It contains examples and
    explainations..
    
    Introduction to the X window system.
    Oliver Jones
    Prentice Hall
    ISBN 0-13--499997-5
    

    The previous notes had some very good information about doing the color
    stuff all on your own -- but, I do not think that's what we want to be
    doing!  I believe that the DECwindows toolkit should offer a routine
    that does shared colormap management for applications.
    
    My goals are:
    
    1) Hide the details of the X visual in use, etc.
    2) Always use the shared color map.
    3) Have colors be as exact as possible.
    
    Goal #1 is for the programmer -- I like to keep things simple.  Goals
    #2 and #3 are for the user.  Goal #2 prevents "carnival colors" from
    happening when a private colormap gets used (quite distressing if it
    has ever happened to you!).  Goal #3 keeps the colors used as correct
    as possible when the shared color map gets full.  Goal #3 is a lot
    harder than you might think.  RGB color space is not perceptually
    uniform -- meaning that in some areas of the space a small change in
    the magnitude of the components causes a large change in how the color
    is viewed.  So, closeness must be handled in a perceptually uniform
    color space like the CIE LAB or CIE LUV spaces.
    
    This problem gets much worse when you start to use color images!  Many
    color images use hundreds of colors.  Most synthetic graphics use only
    a handful...
    
    The ISL (Image Service Library) and the CDA viewers use this kind of
    scheme.  We'd like to get it put into the DECwindows toolkit proper so
    that everyone can use it.
    
    If you are interested in color applications, please send mail to Don
    (SARAH::) Harbison.  He chairs C.A.T. (Color Application Taskforce). 
    There's a meeting coming up in a couple of weeks and we plan to discuss
    color and colormap usage.  Everyone interested in color is welcome!

    Why does Paul suggest using "0" for number of planes in his
    
    	XAllocColorCells
    
    call ?
    
    I would think we should use the number of planes given back in the
    XVisualInfo structure (4 in my case).
    
    But experimentation shows that XAllocColorCells returns 0 (failure)if I give
    it 4 for number of planes, and it returns 1 (success) if I give it 0.
    
    So Paul is right, but what's the reasoning here ?
    
    Maybe I don't understand the XAllocColorCells call at all.  I thought
    it means allocate N pixels in each of P planes, for a total of N*P
    color cells allocated.  In which case using 0 for P would mean allocate
    nothing at all.
    
    Help !
    
    Thanks.
    
    /Eric

    
    Actually there's something missing in this discussion, and it has to do
    with (as Mark says :-) "temporal tricks".  That is, a great many
    "graphic" applications require not only exclusive access to a set of
    color cells (since they will be changing colors) but also need the
    attribute that it be possible to do specific logical operations on the
    data "on-screen" such as "complement mode".  In addition, a number of
    graphic applications may also intermix multi-bit image data with the
    other graphics.  Image data which is typically stored in a format where
    each pixel is in a range from 0 to N in a byte value and where the color
    or greytone values are in a ordered, fixed manner (i.e. 0 = black, 64 =
    white and 1-63 are increasing intensities in-between).
    
    These cases, while perhaps minor cases in *current* "desktop" systems are
    much more common in the workstation market.
    
    X11 is currently pretty weak in this area unless the application is
    willing to stomp on the colors being used by other applications by
    creating a private colormap.  This isn't very friendly.
    
    It *is* possible to create a colormap in a friendly manner that matches
    at least part of the criteria;  by allocating color cells with 1 color
    and N planes, a table of pixel values can be constructed in which
    when XORed with the plane mask bits can be "complemented" (to
    another pixel value that is valid for the user).  Of course, image data
    cannot be directly written or read, each value will need to be
    translated into a value pixel value (a *very* serious performance
    problem).
    
    Because of some things that I am working on right now, I am *very*
    concerned about this area.
    

Mark,

I think that item 1 is a good idea for reasons that I will discuss
shortly.  Item 2 is nice but not always practical.  Theoretically item 3
is already there; in practice????

#1 will turn out to be important for both imaging and synthetic graphics.
I think the implications for imaging I think are obvious and will not persue
them.  For synthetic graphics the primary issue is user customized use of
color to recognize various objects within the application.  The color use
methods of Xtoolkit do not lend themselves to runtime customization.  V2
DECwindows is offering a color mixing widget.  This is clearly intended for
runtime customization of colors.  How do we make the 2 meet with consuming up
large numbers of colors, possibly rendundantly and probably wastefully.  The
answer that I propose has 2 facets.  1) Modify the toolkits color usage model
to reflect run-time customization and 2) provide a set of color value based
color resource setting capabilities.

The reason that resources should be set by color value (RGB, etc) is that the
toolkit can then appropriately allocate and free sharable (when possible)
colors for the various widgets.  In the current model, the application must
keep track of any colors allocated during customization because the values
are assigned to the widgets by pixel.  It also means that the application has
to deal with all the varieties of visuals in duplication of code already in
the toolkit.

#2 can be impractical simply because there are applications which REQUIRE
a color set bigger than what is available to them (because of colors consumed
by other applications).  The best examples of this are colormap animation
applications which require large numbers of WRITABLE color entries.

As an aside, it is not clear to me, from the documentation, what the server
is supposed to do when a client asks for a sharable color of a particular
RGB value when there are no unused colors left in the colormap.  Should it
give an existing color with nearest possible RGB value or should it refuse?
Does the DECwindows server do what the consensus (or something I missed in the
X11 documentation) says?  This is in the case of GreyScale, PseudoColor and
DirectColor.  For TrueColor and StaticGrey the former is definitely used.

Dick

    
    .5 - there is a problem in allocating ALL of the planes, even when
    using a "private" colormap.  For some reason this seems to fail
    (probably due to the failure to allocate the cursor colors).  If you
    are allocating the entire map, then use the alloc all stuff and fake
    your own returns for the plane masks and pixel.
    
    The allocation is:
    
    	num_colors * (2 ** plane_count)
    
    	So you should be able to do 1 color and 4 planes for
    
    		1 * (2**4)
    
    	to get all 16 colors... providing that they are all available!
    

re .5:

Eric, when you allocate a plane, it means that you can write any value you
like into the pixel bit that corresponds to that plane.   But in order to
completely specify the pixel value, you must also know what to fill in for
the rest of the bits.  That is why you must always have at least one pixel.

Another way of looking for it is that
if you ask for 0 planes and 4 pixels, it gives you 4 pixel values with no
guarantee about the relationship of one to another.  If you ask for 2 planes
and 1 pixel, it gives you 4 pixel values which are guaranteed to differ from
one another in exactly two bits.  You are further guarnateed that you can
put any combination of values in those two bits and always have a pixel
value that you "own".

Burns

The reason I'm not saying AllocAll on my XCreateColormap is that it
fails on our monochrome pmax.

To avoid that, I say AllocNone and then use XAllocColors, which seems
to work on both monochrome and color.

but I still don't understand what "0 planes" means...

/Eric

    
    	RE: 1026.8 Converting each pixel value
    
    	You don't actually need to loop through your image and modify
    	the pixel values at runtime.
    
    	If you have an external image, in planes 1-3 say, and you want
    	to stuff it onto your workstation screen in the 3 planes
    	you were given in XAllocColorCells, then you could put your
    	external image into three fullsize XYBitmap's one for each
    	plane, and then XPutImage each bitmap using a GC of
    	(foreground = planemask, background = 0, and planemask = planemask).
    	Each XPutImage will only update one plane. Example:
    
    	unsigned long planes[3], pixel;
    
        if(XAllocColorCells(dpy, colormap, False, planes, 3, &pixel, 1)==0) barf
    
    	Now create 3 GCs using planes[0], planes[1] and planes[3] and
    	do 3 XPutImages to your window.
    
    	It is fairly efficient on GPX hardware as you are not moving excess
    	data into the frame buffer. (A more normal way might be to deepen your
    	image to the depth of the display, say 8, and then XPutImage
    	once from your ZPixmap, but this moves 3 bits of data, and 5
    	bits of zeroes into the frame buffer - wasteful unless you have a
    	DECstation which prefers it that way!).
    
    	Note that before you start you need to clear your window background
    	to the pixel value you were given in XAllocColorCells, because
    	your XPutImage's never write the other planes of your window and
    	they will probably contain XBlackPixelOfScreeen.
    
    	The method also works for PseudoColor on 4, 8 and 24 plane
    	systems (if you don't have other bugs :-)
    
    	No doubt someone else around here has a better idea than the
    	above, but I thought it was pretty neat.
    
    Regards,
    Paul Tallett,
    CEC Karlsruhe	

    	I meant to say 1026.6:
    
     >  Of course, image data
     >  cannot be directly written or read, each value will need to be
     >  translated into a value pixel value (a *very* serious performance
     >  problem).
    
    

    
    Storing images as individual planes is not really an option if you are
    dealing with long established applications which use multi-bit (usually
    8-bits-per-pixel) data.  In addition, to draw the image still requires
    that N single bit image writes must be done... still *far* from optimal
    even if the data is stored in the appropriate format.
    
    

0 planes means that you don't care anything about the bitwise relationships
between the pixel values that you allocate.

1 plane means that you want to pixel values that you allocate to be such given
a particular pixel value that you "own" there is at a bit which you can
toggle and still have another pixel value that you own.

2 planes means the same except that there must be 2 such bits, etc.

Example:

The pixel values you own are 2 and 8.  This is an example of 0 planes.
You can't toggle one bit to get between two values.

The pixel values you own are 2, 3.  This is an example of 1 plane.  If
you toggle bit 0, it takes you from one to the other.

The pixel values you own are 2, 3, 10, 11.  This is an example of 2 planes.
You can toggle any combination of bits 0 and bit 3 and always have a pixel
value that you own.

Note that when you ask for planes and pixels you don't get back the values
in the format I was talking about above.  In the first example, you must have
asked for 0 planes and 2 pixels, and you got 2 and 8 back directly.  In the
second example, you must have asked for 1 plane and 1 pixel.  You got back
a plane mask of 1 (that is the bit that you can toggle) and a pixel value
of 2 (that is the "base" on which you can toggle the bit).  In the third
example, you must have asked for 1 pixel and 2 planes.  You would have gotten
back plane masks of 1 and 8 (the bits you can toggle) and a pixel value of
2 (the base on which you can toggle the bits).

Does this help?

Burns

    RE .2 ( and please forgive me if it's discussed elsewhere )
    
    Why is it that:
    1.  on a GPX-based system I can create a colormap with
    XCreateColormap using AllocAll and then use XStoreColor(s) on any
    pixel value up to and including 254 and 255 (the cursor colors).
    The curso changes color just fine.
    
    but
    
    2. Calling XQueryColors on the default color map 
    with pixel values 254 and/or 255 gives me a 
    BadValue error?
    
    The reason I want to do this is to build an application which uses
    all colormap entries but causes as little immediate impact on the 
    screen as possible.  I want to copy the existing values out of the 
    default color map before mine gets installed and scrumbles up the 
    screen.  Looks like the pointer colors are write-only?
    

Maybe it's a bug in XStoreColors.

--PSW