1This directory contains a subset of the icclib 2.0 distribution for
2use with Ghostscript. The full version of icclib is available from
3Graeme Gill's website: http://web.access.net.au/argyll/color.html
4
5In the near future, we expect to treat icclib much the same way we
6do libjpeg and friends. At that point, it will be available from
7the Ghostscript download locations, but won't actually be included
8in the Ghostscript distribution proper, or in the source tree.
9
10Raph Levien
1118 October 2001
12
13Release notes by Jan Stoeckenius follow (lightly edited by Raph Levien
14to reflect the icclib 2.0 integration):
15
16This patch integrates Graeme W. Gill's icclib code into ghostscript,
17to support ICCBased color spaces for both PostScript and PDF.
18
19The PDF support is as documented in version 1.3 of PDF; see the "PDR
20Reference", 2nd. ed., Sec. 4.5.4 (pp. 165 - 180).
21
22Support for PostScript is essentially identical. An ICCBased color space is
23array of the form:
24
25    [ /ICCBased <dictionary> ]
26
27The recognized entries in the dictionary are:
28
29    N           integer     (Required) The number of color space components,
30                            as in the PDF dictionary. This may be 1, 3, or 4.
31
32    Alternate   array or    (Optional) The alternative color space to use if
33                name        the ICC profile is not useable (for any reason).
34                            If this entry is not provided, its default value
35                            is determined by N, using the rule 1 ==> DeviceGray,
36                            3 ==> DeviceRGB, 4 ==> DeviceCMYK. All this is
37                            the same as in the PDF dictionary.
38
39    Range       array       (Optional) An array of 2 * N numbers, which obey
40                            the relationship Range[2 * i] <= Range[2 * i + 1].
41                            The i'th component of a color, c[i], is
42                            constrained such that:
43
44                                Range[2 * i] <= c[i] <= Range[2 * i + 1]
45
46                            If this entry is not provided, its default value
47                            is an array of length 2 * N with the form
48                            [ 0 1  0 1 ... ]. All of this is the same as for
49                            the PDF dictionary.
50
51    DataSource  file or     (Required)The ICC profile data. If this is a
52                string      file it must be positionable.
53
54With the exception of running out of memory, most errors discovered while
55reading the profile will result in the alternative space being used.
56
57
58New Files:
59
60  src/gsicc.c
61    Implementation of the methods associated with the ICCBased color space
62    structure (a gs_color_space_s structure of type gs_color_space_index_CIEICC).
63    The gs_cspace_build_CIEICC procedure is also implemented in this file.
64
65  src/gsicc.h
66    Definition of the gs_cie_icc_s structure, which is the essential
67    parameter structure for ICCBased color spaces. The files in this
68    structure are all straightforward, except for the file_id field. This
69    latter field is compared with the read_id and write_id of a stream,
70    to verify that the stream is still valid. This is the same mechanism
71    as is used by the ref structure, and for the same reason.
72
73  src/zicc.c
74    Implementation of the .seticcspace operator, which is used to set the
75    current color space to be an ICCBased color space.
76
77  src/icclib.mak
78    Makefile for building the icclib code (which is in a separate directory).
79    The mechanism used is identical to that used by zlib.mak.
80
81  lib/gs_icc.ps
82    Implementation of the ICCBased color space specific routine in
83    colorspacedict. This routine is much more extensive that those used
84    for the other color spaces, both due to the greater complexity of the
85    color space and because we have chosen to implement much of the error
86    checking in this routine.
87
88    NB: To disable support for ICCBased color spaces, replace "NOCIE" in
89        this file with "true". Though ICCBased will still be a recognized
90        color space family, the alternative space will always be used.
91
92  gs_icclib/icc.c
93  gs_icclib/icc.h
94  gs_icclib/icc9809.h
95    The gs_icclib directory is the default location of the icclib code.
96    The files in this directory are identical to those of the usual
97    distribution of this library.
98
99
100Modified Files:
101
102    src/gdevpdfc.c
103      Added support for ICCBased color spaces to the pdf_color_space procedure.
104      These are effectively translated into themselves, with the DataSource
105      component replaced by a (PDF) stream.
106
107    src/gdevpx.c
108      Added ICCBased to the set of color spaces that
109      pclxl_can_handle_color_space reports as one that cannot be handled.
110
111    src/gscie.c
112      Added support for ICCBased color spaces in the cie_cs_common_abc
113      procedure. Also exported gx_cie_common_complete (previously
114      cie_common_complete) and gx_cie_load_common_cache (previously
115      cie_load_common_cache) for use in gsicc.c.
116
117    src/gscie.h
118      Modified the definitions of st_cie_common and st_cie_common_elements
119      to be public.
120
121    src/gsciemap.c
122      Removed the definition of the macro CIE_CHECK_RENDERING (it is now in
123      gxcie.h). Exported gx_cie_remap_finish (previously cie_remap_finish)
124      for use in gsicc.c.
125
126    src/gscolor.c
127      Added support for ICCBased color spaces in gs_currentrgbcolor.
128
129    src/gscolor1.c
130      Added support for ICCBased color spaces in gs_currentcmykcolor.
131
132    src/gscscie.c
133      Exported st_cie_common, st_cie_common_elements, gx_concrete_space_CIE,
134      gx_install_CIE, gx_set_common_cie_defaults (previously
135      set_common_cie_defaults), and gx_build_cie_space (previously
136      build_cie_space) for use in gsicc.c.
137
138    src/gscspace.h
139      Added the gs_icc_params data structure (for ICCBased color spaces),
140      and the associated type indicator (gs_color_space_index_CIEICC). Also
141      broke what had been the gs_base_color_space structure into two, with
142      gs_small_base_color_space covering all the prior base color spaces,
143      and gs_base_color_space covering these and the ICCBased color space.
144      See the comments in the file for an explanation as to why this was
145      necessary.
146
147    src/gscssub.c
148      Added code to allow ICCBased color spaces to be substituted for the
149      device specific color spaces. This is necessary to support the
150      DefaultDevice* color spaces in PDF.
151
152    src/gxcie.h
153      Moved the definition of the CIE_CHECK_RENDERING macro to this file
154      (it was in gsciemap.c). Added prototypes for st_cie_common,
155      st_cie_common_elemets_t, gx_set_common_cie_defaults,
156      gx_cie_load_common_cache, gx_cie_common_complete, gx_install_CIE,
157      gx__build_cie_space, and gs_concrete_cspace_CIE.
158
159    src/gxshade.c
160      Added support for ICCBased color spaces in shade_init_fill_state.
161
162    src/icie.h
163      Added a prototype for cie_set_finish.
164
165    src/zcie.c
166      Exported cie_set_finish (previously set_cie_finish) for use in zicc.c
167      (the name change maintains consistency with other exported CIE-specific
168      interpreter routines).
169
170    src/lib.mak
171      Added the sicclib.dev feature device, and the associated compilation
172      directives and dependency lists. Also updated the dependency lists
173      for gscie.c and gxshade.c (both now require gsicc.h).
174
175    src/int.mak
176      Added the icc.dev feature device,  and the associated compilation
177      directives and dependency lists. This pdf.dev feature device now
178      lists icc.dev as a prerequisite.
179
180    src/devs.mak
181      Updated the dependency list for gdevpdfc.c.
182
183    src/bcwin32.mak
184    src/dvx-gcc.mak
185    src/msvc32.mak
186    src/msvclib.mak
187    src/openvms.mak
188    src/os2.mak
189    src/ugcclib.mak
190    src/unix-gcc.mak
191    src/unixansi.mak
192    src/unixtrad.mak
193    src/watc.mak
194    src/watclib.mak
195    src/watcw32.mak
196      Added a default definition for ICCSRCDIR, the source directory for
197      the icclib code.
198
199    src/gs.mak
200      Added default definitions for ICCGENDIR, ICCOBJDIR, ICCI_ (ICC specific
201      include directories), and ICCF_ (currently empty).
202
203
204    lib/pdf_draw.ps
205      Added ICCBased color space specific procedures for csncompdict and
206      defaultdecodedict. Modified the ICCBased color space procedure in
207      csrdict to map a PDF-form color space to the PostScript form.
208
209    lib/pdf__ops.ps
210     Added ICCBased color space specific procedure to CSdict and Cdict.
211
212Additional notes by Jan Stoeckenius:
213
2141. The color produced when ICCBased color spaces are employed is
215   dependent on the installed color rendering dictionary. For the
216   default X11 device, this dictionary does not provide correction
217   for the relative white point (at least, not as far as we can tell).
218   ICC profiles use the D50 white point. In the absence of white point
219   adjustment, "white" in the associated color space appears to be
220   a moderate yellow on the output device (other colors are similarly
221   "red-shifted").
222
223   This arrangement has the advantage of making it obvious when ICCBased
224   color spaces are supported (useful for testing). On the other hand,
225   the output is probably not what the user intended.
226
227   If you have any devices with known "good" color rendering dictionaries,
228   it would be useful to test ICCBased color space support on those
229   devices as soon as possible.
230
2312. The tests we have run do not exercise the memory handling facilities
232   in ghostscript to any extent. The support for ICCBased color spaces
233   involves two new structures, for which we have provided structure
234   descriptors. We believe these have been correctly constructed, and
235   that the one reference-counted structure is being handled properly,
236   but we have no simple way of testing for this.
237
2383. Changes were required in an unexpectedly large number of files
239   (9 new files, 34 existing files [these figures refer to the
240   integration into 7.00 - RLL]), though in many cases only a few
241   lines needed to be modified.
242
243   The primary reason for this is that the graphic library color space
244   code severely violates the principles of object-oriented programming.
245   Color space objects have a visible type indicator, and this type is
246   directly used in many places. When adding a new color space type, it
247   was not sufficient to create the associated methods. We also had to
248   search the code for all places in which a color space type indicator
249   was explicitly accessed.
250
251   We believe we have found all the places where this occurs, and have
252   modified them appropriately (see the ReleaseNotes file for details).
253   On the other hand, we have not come remotely close to testing all of
254   these changes, nor is there any easy test to see if there are places
255   we missed.
256
257   When Peter was the only person working on the graphic library,
258   this situation was bothersome but probably not critical. In the
259   new environment in which ghostscript is being developed, we believe
260   this situation will lead to serious problems. We recommend that a
261   project be started to make the color space code much more object-
262   oriented, by creating color space methods for all of the required
263   color space properties.
264
2654. The current method of "inline" storage of alternative/base color spaces
266   is becoming hard to maintain. Strictly speaking, ICCBased color spaces
267   cannot be implemented within this mechanism: the color spaces may be
268   (and are) used as alternative color spaces for Separation and DeviceN
269   color spaces, and may in turn access such color spaces as their own
270   alternative color space. We hacked around this problem by disallowing
271   the latter possibility, and introducing yet another layer in the
272   color space hierarchy. The class gs_base_color_space is now split
273   into gs_small_base_color_space (all of the previous base color spaces)
274   and gs_base_color_space (gs_small_base_color_space and ICCBased color
275   spaces). This is an unholy mess, but at least it seems to be functional.
276
277   As the number of layers in the color space hierarchy grows, so does the
278   potential for serious and well-hidden problems. The reason is that
279   pointers to alternative/base color spaces may point into the middle of
280   an object. If such a pointer is accessible via the heap, and is subject
281   to relocation, the location of the structure descriptor will be read
282   incorrectly. By the time this error is apparent, much of the affected
283   memory may be overwritten. Tracing such problems is typically quite
284   time-consuming.
285
286   The original guard against this problem was to perform all color space
287   assignments by value. This worked when Peter was the only person regularly
288   changing the code, and may continue to work under the current arrangement.
289   We believe, however, that this situation will cause trouble in the
290   future.
291
292   We recommend that the current color space mechanism be discarded. A new
293   mechanism should allow alternative/base color spaces to be included by
294   reference rather than by value. Such a mechanism should also move the
295   generic color space parameters (number of components, additive/subtractive
296   indicator, etc.) into the base structure, even if these parameters are
297   fixed for certain color spaces.
298
2995. The PDF device code currently attempts to translate PostScript's
300   CIEBased color spaces into the more restrictive set of CIE color spaces
301   in PDF. Many color spaces cannot be translated directly, and the code
302   will fail if such a color space is encountered.
303
304   We have generalized this code to handle ICCBased color spaces, which
305   effectively are translated to themselves. A much more complete solution
306   could be provided by mapping PostScript's CIEBased color spaces into
307   ICCBased color spaces in PDF. Essentially all CIEBased color spaces
308   could be handled in this manner (via sample and generation of a lookup
309   table).
310
311