# coyote: CGSETCOLORSTATE

- coyote/Graphics
- coyote/Utilities
- [Source code]

Description

      Provides a device-independent way to set the color decomposition state of the
      current graphics device. Devices that do not have a DECOMPOSED keyword to the
      DEVICE command are assumed to be in indexed color mode always.
      I have removed the Z-graphics buffer from being controlled by this program. I
      do so reluctantly, but I am pragmatic enough to realize that progress forward
      is necessarily slow and that I must recognize the reality of legacy IDL code.
      My personal view is that all graphics routines should use 24-bit decomposed
      color. There are myriad advantages, but basically they boil down to this:
      (1) You have 16.7 million colors available to you simultaneously, and (2) you
      don't have to contaminate color tables to use drawing colors. Coyote Graphics
      routines are in the habit of switching out of whatever color mode the user happens
      to be using, into 24-bit decomposed color mode, then switching back when finished
      with its business. But, it is impossible to do this correctly in the Z-graphics
      buffer.
      The reason for this is that in the Z-graphics buffer, you need to switch not only
      the color mode, but also the pixel depth. In other words, I would prefer to set
      the Z-graphics buffer up like this::
          Set_Plot, 'Z'
          Device, Decomposed=1, Set_Pixel_Depth=24
      But, if I do that, then I need to set it back (for 99 people out of a 100) like this::
          Device, Decomposed=0, Set_Pixel_Depth=8
      Unfortunately, using this command will erase whatever is in the Z-graphics buffer!
      My solution to this problem is to leave it to the user to configure the Z-graphics buffer
      the way they want it. If you configure it to use 24-bit decomposed color, all of the Coyote
      Graphics routines will work as they normally do. If you configure it to use 8-bit indexed color,
      which is the default configuration, then it will work "normally", but you will be in great
      danger of contaminating the system color table. The reason for this is that Coyote Graphics
      cannot "restore" the entry color table in the Z-buffer without obliterating what is already
      in the graphics window. Users who work with indexed color are probably already very much
      aware of this problem, so it shouldn't surprise them. (They might not expect this with
      Coyote Graphics, but this is the price that has to be paid.)
      My suggestion is to put the Z-graphics configuration in your IDL startup file. Set it
      up in 24-bit decomposed color mode, use Coyote Graphics to do all your graphical output,
      and you will find things working perfectly.
      See `Configuring the Z-Graphics Buffer for Coyote Graphics <http://www.idlcoyote.com/cg_tips/configz.php>`
      for additional information.

Categories

      Graphics, Utilities

Params

      state: in, required, type=integer, default=0
           Set to 1 to set the current graphics device to decomposed color. Set to 0
           to set the current graphics device to indexed color. Devices lacking a
           DECOMPOSED keyword are assumed to be perpetually in indexed color mode.
           The Z-graphics buffer is always unchanged after the 24 Dec 2011 update.

Keywords

      currentstate: out, optional, type=integer
          The current decomposition state of the current graphics device when the
          program is called. A 1 indicates decomposed color. A 0 indicates indexed
          color.
      depth: out, optional, type=integer
          The currnet pixel depth of the graphics device.
      zdepth: in, optional, type=integer
          The pixel depth of the Z-graphics device. Set to 8 or 24. Applies ONLY
          when setting the Z-graphics device state to 0. If undefined, the current
          depth of the Z-graphics device is unchanged from its current state. No
          longer used after 24 Dec 2011 update. Code still in place, however.

Examples

      To set the device in color decomposition mode, then return it, do something like this::
         cgSetColorState, 1, CurrentState=theState
         ...
         cgSetColorState, theState

Author

      FANNING SOFTWARE CONSULTING::
          David W. Fanning
          1645 Sheely Drive
          Fort Collins, CO 80526 USA
          Phone: 970-221-0438
          E-mail: david@idlcoyote.com
          Coyote's Guide to IDL Programming: http://www.idlcoyote.com

History

      Change History::
         Written, 16 November 2010. DWF.
         Changes to include SET_PIXEL_DEPTH in Z-graphics buffer. 19 Nov 2010. DWF.
         Allow PostScript 7.0 to set the decomposition keyword. 12 Dec 2010. DWF.
         Added DEPTH and ZDEPTH keywords. 31 Dec 2010. DWF.
         Added a do-nothing NULL device to Case statement. 4 Jan 2011. DWF.
         Removed the Z-graphics buffer from control by this program. 24 Dec 2011. DWF.
         Added back the ability to set decomposed state for the Z-buffer, but only
            if the depth buffer is 24-bits or higher. 25 May 2012. DWF.
         Renamed SetDecomposedState to cgSetColorState. 5 November 2013. DWF.

Copyright

      Copyright (c) 2010-2013, Fanning Software Consulting, Inc.