Configuring the Z-Graphics Buffer

QUESTION: I'm trying to use AL_Legend in the Z-graphics buffer, but I'm getting really weird results. Can you explain what is happening?

Here is the code I am using to produce a line plot as a PNG file. Code, by the way, which I have used for years with no problems whatsoever!

The odd thing is that the first time I run this code, I get the PNG file shown on the left in the figure below, and the second time I run it I get the figure shown on the right. Neither is correct. What's up with that!?

Strange results in the Z-graphics buffer.

 

ANSWER: This is an interesting problem that has nothing to do with AL_Legend, as it happens. Rather, it is part and parcel of the design philosophy of the Coyote Graphics routines, which AL_Legend is using. Allow me to explain what the problem is and why I am caving into the forces of the Dark Side on this particular point.

It is a tenet of the Coyote Graphics System that all graphics output should be done in 24-bit decomposed color mode. There are two primary reasons for this: (1) You have immediate access to 16.7 colors simultaneously, and (2) there is no danger of contaminating image color tables with drawing colors in this color mode. A secondary reason is that you paid a lot of money for a 24-bit graphics card and you ought to use it. We are starting the 12th year of the 21st century. There is no reason to do graphics the way we did graphics in the 1970s.

Another way to say this is that the days of indexed color are over. Done. Kaput. Although, I have to admit, there is a suprisingly large number of IDL programmers who don't realize this yet. But, I have always considered it part of my job to move things along, however slowly.

I realized that the transition to decomposed color was going to be slow. No one wants to learn anything new after, say, the age of 25 or so, and there are piles and piles of legacy IDL code out there. No one, I admit, wants to rewrite it. So, Coyote Graphics are, in general, tolerant of the old way of doing things. They do the "conversion" of the old way to the new way behind the scenes and out of sight of the audience. But, here is a case where I have pushed too soon and have gone a bridge too far.

The culprit is the program SetDecomposedState, whose job it is to switch all Coyote Graphics routines into 24-bit decomposed color mode in a device independent way. (There are several other programs involved, too, so you will need a Coyote Library update.) If a device can be put into this mode, SetDecomposedState will do it. All Coyote Graphics output is done in this state, if possible.

This is what is causing the problem here. You are writing the program is an old-school way, and SetDecomposedState is trying to drag you into the modern world, and in the case of the Z-graphics buffer, the result is not pretty. Let me explain why.

Using a 24-Bit Z-Graphics Buffer

Up until IDL 6.4 the Z-graphics buffer was an 8-bit device. But, in IDL 6.4 this changed and it became possible to make the Z-graphics buffer a 24-bit device. This is done with the Set_Pixel_Depth keyword. So, to make the Z-graphics buffer behave identically to your default graphics display window, you set it up like this.

   Set_Plot, 'Z'
   Device, Decomposed=1, Set_Pixel_Depth=24

There are about three people in the world who know this is possible and actually use this capability. Unfortunately, I am one of them.

Thus it was that when I wrote SetDecomposedState I added the ability to set the Z-graphics buffer up like this. I admit now it was a mistake. Too much, too soon. Ninty-five million people still think the Z-graphics buffer is an 8-bit device and want to use it as such.

Actually, to be fair, putting the Z-graphics buffer in this state is not the problem. Putting it back into its previous state is the real problem! It is easily done.

   Device, Decomposed=0, Set_Pixel_Depth=8

Unfortunately, because of the way the Z-graphics buffer works, when you change the pixel depth like this, you actually erase what is currently in the 24-bit buffer. This, as you can imagine, is a disaster! So, I didn't do it in SetDecomposedState.

This is why you get such weird results. The configuration of the Z-graphics buffer changed underneath you in a way you didn't anticipate. Had you been using Coyote Graphics routines to draw your graphics, it wouldn't have made any difference to you, and you would never have noticed that things had changed. But, because you are using the old IDL routines, which don't work well in this environment, things went weird on you.

What I have decided to do in the latest version of SetDecomposedState is allow the user to configure the Z-graphics buffer as they wish, and honor their selection. If you are like me, and use Coyote Graphics exclusively, then I would put the following lines of code in your IDL start-up file.

   thisDevice = !D.Name
   Set_Plot, 'Z'
   Device, Decomposed=1, Set_Pixel_Depth=24, Set_Resolution=[640,512]
   Set_Plot, thisDevice

Now your Z-graphics buffer will be configured exactly like any normal IDL graphics window and any program that works in the display window will work identically in the Z-graphics buffer. Otherwise, you can configure the Z-graphics buffer to your needs and you won't have to be concerned with Coyote Graphics routines changing your choices for you.

With the new version of SetDecomposedState, I would write your program like this.

    thisDevice = !D.Name
    Set_Plot, 'Z'
    Device, Set_Resolution=[500,500], Decomposed=1, Set_Pixel_Depth=24
    cgPlot, Indgen(10), Color='Blue'
    cgPlot, Indgen(10)+1, Color='Red', /Overplot
        ; Add a legend.
    Al_Legend, ['al_legend','plot','oplot'], LineStyle=[-99,0,0], /Box, $
        Color=['black', 'blue', 'red'], /Right, /Bottom
    void = cgSnapshot(File='test', /PNG, /NoDialog)
    Set_Plot, thisDevice

Using AL_Legend in the Z-graphics buffer.

 

Note that you will need the Coyote Library update of 25 December 2011 to run the code described in this article.

Version of IDL used to prepare this article: IDL 7.1.