From: sns@bondi.jpl.nasa.gov (Sam Southard)
Subject: Re: new FAQ? (programming) masking Pixmaps *efficiently*
Keywords: Pixmap, mask, bitmap, graphic context
Organization: SAR Systems Development & Processing, JPL
Date: Fri, 11 Dec 1992 18:02:30 GMT

Sorry for the length of this one...

I read through all I could find & save (including the FAQ) about drawing to
windows and having one pixmap overlay another with one or more pixel values in
the overlaying pixmap being transparent.  The two methods I decided would be
appropriate were using the clip_mask feature of the graphics context, or by
using FillStippled.

However, there was a note in the Xlib programming manual about the server
having a "best" size (or perhaps a list of best sizes) for stipples, with no
corresponding limitation (at least not that I saw) for using clip_mask.  Since
my application will have arbitrarily-sized images, I decided that I would use
the clip_mask.

Then I read the following response to someone else's related question:

In article <1992Dec11.102303.28704@thunder.mcrcim.mcgill.edu> mouse@thunder.mcrcim.mcgill.edu (der Mouse) writes:
>In article <1g45bpINNavm@agate.berkeley.edu>, beorn@elk.Berkeley.EDU (Beorn Johnson) writes:
>> The pixmaps need to be masked such that only the non-zero (or
>> non-background color?) PIXELS are copied to the screen.
>
>> I can, of course, use the "clip_mask" feature of the graphics
>> context.  [This turns out to be too slow on at least one server.]
>
>The server in question is probably doing the common thing and
>converting clip-masks to rectangle lists.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...
>If you have a bitmap somewhere that is a mask, set to 1 where you want
>pixels drawn and 0 elsewhere, you could set that as the stipple in the
>GC and do a fill with fill-style FillStippled.  (Repeat for each
>bitplane, for multi-color pictures.)

The item about which I'm specifically concerned is indicated with "^".  My
concern is about the server "doing the common thing and converting clip-masks
to rectangle lists."  Specifically, when is this conversion done?

I had anticipated setting the clip_mask to a given pixmap and then being free
to do whatever I wanted with that pixmap.  Then, when I actually did something
which used that GC, it would auto-magically take care of things for me.
However, the conversion method implies that either:

(1) I must set the clip_mask every time it is changed (or just before it is
	used, if it has changed since the last use).  This is a little less
	convinient, but would probably perform acceptably, assuming the
	clip_mask feature would perform acceptably at all.
(2) The server does this conversion just before every GC use.  This is likely
	to be quite slow.
(3) The server keeps track of then the clip_mask pixmap is changed and
	converts the when it changes (or perhaps before a use if the pixmap
	has been changed).

I re-examined the Xlib reference manual to see if maybe using stipple was a
better alternative, given the above information.  It appears that fill_style is
not significant for things such as XCopyArea.  Is this a misprint, or, if I do
decide to use FillStippled, must I retain all graphics commands and re-issue
them when an area of the window is exposed?  I had planned on retaining a
pixmap with the window contents for this purpose.  I suppose that overlay
contents are not likely to be extremely complicated, so retaining commands
would not be such a horrible thing.

Perhaps there's a better way to do what I'm trying to do, so I'll give a little
more information on that.

I'm basically trying to emulate a mid-range (at least what I consider a mid-
range) display device.  Those characteristics are at least 8 bit planes for
regular graphics, a text overlay plane, and a graphics overlay plane (perhaps
two bits for the graphics overlay).  Each bitmap (main, text overlay, and
graphics overlay) can contain essentiall arbitrary information.  I don't care
about supporting X devices with fewer than 8 bits.  I do need to be able to
manipulate color LUTs, so read/write LUT entries are a must (at least for
devices which support it - I would want the program to work in a semi-crippled
way on StaticGrey visuals, for exmaple).

If my understanding of things is correct, if I were to actually use bit-planes
for my colors and wanted to run in the default colormap, I would only have at
most 7 bit-planes available on an 8-bit device (some colors would be used by
the window manager, other applications, etc.).  If I use one bit for text and
one for graphics overlay planes, I'm only left with 32 colors (5 bits) for the
main graphics, which is too few.  If I combine the two overlay planes I'm left
with 64 colors, which is just barely acceptable.

I'd planned on having each source pixmap (main, text overlay, and graphics
overlay) as an 8-bit pixmap (assuming the screen depth was 8 bits) and using
different color map cells for each pixmap.  I would then keep an additional
1-bit pixmap for each of the text & graphics overlay planes.  The 1-bit
pixmaps would be used for clip_mask.  I could then just use XCopyArea in the
appropriate order and I'd have my overlay planes.

If I used 3 colors (plus the "transparent" color) for the graphics overlay,
plus 1 color for text overlay, I would still be left with 150-200 colors for
the main graphics.  I could add significantly more colors for the overlay
planes (say 7 and 3) and still be left with about the same number of colors
for text.

In a related question, where would I go to find details on any X extensions (or
non-extensions, though I've not seen anything in the standard documents) which
would allow me to detect overlay planes of the device on which I'm working and,
if the device has such planes, how to use them?

Thanks for any help you can give,
Sam Southard, Jr.