File: cgsetcolorstate.pro

package info (click to toggle)
coyote 2019.01.29-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster
  • size: 6,316 kB
  • sloc: python: 184; makefile: 14; sh: 13
file content (196 lines) | stat: -rw-r--r-- 10,247 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
; docformat = 'rst'
;
; NAME:
;   cgSetColorState
;
; PURPOSE:
;   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.
;
;******************************************************************************************;
;                                                                                          ;
;  Copyright (c) 2010, by Fanning Software Consulting, Inc. All rights reserved.           ;
;                                                                                          ;
;  Redistribution and use in source and binary forms, with or without                      ;
;  modification, are permitted provided that the following conditions are met:             ;
;                                                                                          ;
;      * Redistributions of source code must retain the above copyright                    ;
;        notice, this list of conditions and the following disclaimer.                     ;
;      * Redistributions in binary form must reproduce the above copyright                 ;
;        notice, this list of conditions and the following disclaimer in the               ;
;        documentation and/or other materials provided with the distribution.              ;
;      * Neither the name of Fanning Software Consulting, Inc. nor the names of its        ;
;        contributors may be used to endorse or promote products derived from this         ;
;        software without specific prior written permission.                               ;
;                                                                                          ;
;  THIS SOFTWARE IS PROVIDED BY FANNING SOFTWARE CONSULTING, INC. ''AS IS'' AND ANY        ;
;  EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES    ;
;  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT     ;
;  SHALL FANNING SOFTWARE CONSULTING, INC. BE LIABLE FOR ANY DIRECT, INDIRECT,             ;
;  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED    ;
;  TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;         ;
;  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND             ;
;  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT              ;
;  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS           ;
;  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.                            ;
;******************************************************************************************;
;
;+
;   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.
;-
PRO cgSetColorState, state, CURRENTSTATE=currentState, DEPTH=depth, ZDEPTH=zdepth

    Compile_Opt idl2
    
    On_Error, 2
    
    ; Set to indexed color if you are not told differently.
    state = Keyword_Set(state)
    
    ; Get the current state and pixel depth.
    currentState = cgGetColorState(DEPTH=depth)
    
    ; Set the decomposition state, if you are able. Otherwise assume
    ; indexed color mode.
    CASE StrUpCase(!D.Name) OF
    
       'PS': IF (!Version.Release GE 7.1) THEN Device, Decomposed=state
                             
        'Z': BEGIN ; Z-Graphics Buffer ; See program notes for why the Z-buffer is no longer controlled here.
;             IF Float(!Version.Release) GE 6.4 THEN BEGIN
;                IF N_Elements(zdepth) NE 0 THEN BEGIN
;                   IF (zdepth NE 8) AND (zdepth NE 24) THEN Message, 'ZDEPTH must be set to 8 or 24.'
;                ENDIF
;                CASE state OF
;                    0: BEGIN
;                    
;                        ; Set depth if you have it, otherwise, just leave it alone.
;                        IF N_Elements(zdepth) NE 0 THEN BEGIN
;                            Device, Decomposed=state, Set_Pixel_Depth=zdepth
;                        ENDIF ELSE BEGIN
;                            Device, Decomposed=state
;                        ENDELSE
;                        END
;                    1: Device, Decomposed=state, Set_Pixel_Depth=24
;                 ENDCASE
;             ENDIF
             
             ; I am going to allow the user to set the decomposed state, but only if
             ; they are using a buffer depth that will allow that.
             IF (depth GE 24) THEN Device, Decomposed=state
             END
             
        'MAC': BEGIN
             IF (Float(!Version.Release) GE 5.2) THEN Device, Decomposed=state
             END
             
         'X': Device, Decomposed=state
         
         'WIN': Device, Decomposed=state
         
         'NULL':
         
         ELSE: Message, 'Unrecognized device. Assuming indexed color state.', /INFORMATIONAL
         
    ENDCASE
    
END