1 /* Copyright (C) 2001-2006 Artifex Software, Inc. 2 All Rights Reserved. 3 4 This software is provided AS-IS with no warranty, either express or 5 implied. 6 7 This software is distributed under license and may not be copied, modified 8 or distributed except as expressly authorized under the terms of that 9 license. Refer to licensing information at http://www.artifex.com/ 10 or contact Artifex Software, Inc., 7 Mt. Lassen Drive - Suite A-134, 11 San Rafael, CA 94903, U.S.A., +1(415)492-9861, for further information. 12 */ 13 14 /* $Id: gsicc.h 8022 2007-06-05 22:23:38Z giles $ */ 15 /* Structures for ICCBased color space parameters */ 16 /* requires: gspsace.h, gscolor2.h */ 17 18 #ifndef gsicc_INCLUDED 19 # define gsicc_INCLUDED 20 21 #include "gscie.h" 22 23 /* 24 * The gs_cie_icc_s structure will exist in all instantiations of the 25 * graphic library, whether or not they provide support of the ICCBased 26 * color spaces. If such support is not provided, we cannot assume that 27 * the ICC support library (icclib) is included in the source code, so 28 * we also cannot assume that the header file icc.h is available during 29 * compilation. Hence we cannot include icc.h in this file. 30 * 31 * The following two opaque declarations are used to get around this 32 * limitation. 33 */ 34 struct _icc; 35 struct _icmLuBase; 36 37 /* 38 * ICCBased color spaces are a feature of PDF 1.3. They are effectively a 39 * variation of the CIEBased color spaces, in which the mapping to XYZ space 40 * is accomplished via an ICC profile rather than via matrices and procedures 41 * in a color space dictionary. 42 * 43 * For historical reasons, the graphic library code for mapping XYZ colors 44 * to the device color model assumes that a CIEBasedABC color space is 45 * being used (there is a small exception for CIEBasedA). The mechanism used 46 * by the CIE joint caches is dependent on this. To remain compatibile with 47 * this arrangement, the gs_cie_icc_s structure must contain the 48 * gs_cie_common_elements prefix, even though this structure serves only 49 * as carrier of the white and black point information (all other parameters 50 * are set to their default values). 51 * 52 * The icclib code was originally created to read from a file using the 53 * stdio library. We can generalize the module to work with a positionable 54 * stream with a simple change of header files. Somewhat more difficult 55 * issues are involved adapting icclib to the graphic libraries memory 56 * management scheme. 57 * 58 * The stream that comprises the filter is initially a PostScript object. 59 * As such, it subject save/restore, garbage collection, relocation, may 60 * be accessed and closed explicitly by the PostScript code. Most 61 * significantly, a given stream structure instance may be re-used once it 62 * has been closed. 63 * 64 * Unfortunately, the icclib code retains the stream pointer for 65 * (potentially) long periods of time, and is blissfully unaware of all of 66 * these possibilities. We also would like very much to avoid having to 67 * make it aware of these complexities (so that we may easily use future 68 * upgrades). The following methods are used to achieve this goal: 69 * 70 * This color space structure may be used only so long as the PostScript 71 * color space array that generated it is still accessible. If this array 72 * is accessible, the stream is also accessible. Hence, we do not need to 73 * provide access to that stream via this this object, nor can we loose 74 * the stream via save/restore. 75 * 76 * The color space objects themselves (the top-level profile structure 77 * pointed to by picc and the lookup object pointed to by plu) are 78 * allocated in non-garbage collected ("foreign") memory, so we do not 79 * have to indicate access via this structure, nor do we have to be 80 * concerned about relocation of these structures. 81 * 82 * (Supporting relocation in icclib would require significant changes 83 * to the library, which would complicate any future upgrades. To 84 * support garbage collection would, at a minimum, require a modified 85 * set of operands for the allocation procedure used by the library, 86 * which also seems ill advised.) 87 * 88 * Because the input stream structure is re-locatable, it is necessary 89 * to update the stream pointer held in the profile data structure 90 * prior to any call to the module. We retain a pointer to the stream 91 * in the gs_cie_icc_s structure, for which a structure descriptor is 92 * provided, and use this to update the value held by the icc library. 93 * The method update_file_ptr has been added to the _icc structure to 94 * facilitate this process. 95 * 96 * In principle, a user should not close the stream object included 97 * in a color space until that space is no longer needed. But there is 98 * no language-level mechanism to detect/prevent such activities, so 99 * we must deal with that possibility here. The method employed 100 * mimics that used with PostScript file objects. The file_id field is 101 * initialized to the value of (instrp->read_id | instrp->write_id), 102 * and is compared with this value prior to any call. If the values are 103 * no longer the same, the stream has been closed and a suitable 104 * error is generated. 105 */ 106 struct gs_cie_icc_s { 107 gs_cie_common_elements; 108 109 /* number of components, and their associated range */ 110 uint num_components; 111 gs_range4 Range; 112 113 /* stream object, and the associated read id */ 114 unsigned short file_id; 115 stream * instrp; 116 117 /* the following are set when the structure is initialized */ 118 119 /* must the profile connection space undergo an L*a*b* ==> XYZ conversion */ 120 bool pcs_is_cielab; 121 122 /* top-level icclib data structure for the profile */ 123 struct _icc * picc; 124 125 /* "lookup" data structure in the ICC profile */ 126 struct _icmLuBase * plu; 127 128 /* icclib file object for ICC stream */ 129 struct _icmFile * pfile; 130 }; 131 132 /* 133 * The gs_cie_icc_s structure is responsible for foreign memory that must be 134 * freed when the object is no longer accessible. It is the only CIE space 135 * structure that contains such pointers. We make use of the finalization 136 * procedure to handle this task. 137 */ 138 #define private_st_cie_icc() /* in gscsicc.c */ \ 139 gs_private_st_suffix_add1_final( st_cie_icc, \ 140 gs_cie_icc, \ 141 "gs_cie_icc", \ 142 cie_icc_enum_ptrs, \ 143 cie_icc_reloc_ptrs, \ 144 cie_icc_finalize, \ 145 st_cie_common_elements_t,\ 146 instrp ) 147 148 /* typedef struct gs_cie_icc_s gs_cie_icc; */ /* in gscspace.h */ 149 150 151 /* 152 * Build an ICCBased color space. 153 * 154 * As with all of the CIE base color space constructurs, this will build 155 * an gs_cie_icc_s structure with a reference count of 1 (not 0). If the 156 * color space is passed to gs_setcolorspace, that procedure will increment 157 * the reference count again. To prevent the color space from being allocated 158 * permanently, the client should call cs_adjust_count(pcspace, -1). 159 * THIS IS A BUG IN THE API. 160 * 161 * The client is responsible for initializing the alternative color space 162 * information. 163 */ 164 extern int gs_cspace_build_CIEICC( gs_color_space ** ppcspace, 165 void * client_data, 166 gs_memory_t * pmem ); 167 168 int 169 gx_load_icc_profile(gs_cie_icc *picc_info); 170 171 #endif /* gsicc_INCLUDED */ 172