Tryag File Manager
Home
-
Turbo Force
Current Path :
/
proc
/
self
/
root
/
usr
/
share
/
doc
/
lcms-devel-1.18
/
Upload File :
New :
File
Dir
//proc/self/root/usr/share/doc/lcms-devel-1.18/LCMSAPI.TXT
little cms Engine 1.18 API Definition by Marti Maria --------------------------------------------------- Index ----- 0 - Compilation toggles 1 - Profile & Transform functions 2 - Information functions 3 - On-the-fly profile creation functions 4 - Build-In profiles 5 - White point 6 - Gamma handling 7 - Error handling 8 - Conversion functions 9 - CIECAM97s/CIECAM02 10 - Profile creation functions 11 - LUT manipultation 12 - Named color functions 13 - PostScript 14 - CGATS.13 - 200 0 - Compilation toggles _________________________________ Generally, there is no need to touch anything. Comment/uncomment if the testbet hints to do so. Optimization mode. USE_ASSEMBLER Is fastest by far, but it is limited to Pentium. USE_FLOAT are the generic floating-point routines. USE_C should work on virtually any machine. Define this if you are using this package as a DLL (windows only) LCMS_DLL Define this if you are compiling using this package as a DLL (windows only) LCMS_DLL_BUILD Uncomment if you are trying the engine in a non-windows environment like linux, SGI, VAX, FreeBSD, BeOS, etc. NON_WINDOWS Uncomment this one if you are using big endian machines (only meaningful when NON_WINDOWS is used) USE_BIG_ENDIAN Uncomment this one if your compiler/machine does support the "long long" type This will speedup fixed point math. (USE_C only) USE_INT64 Some machines does not have a reliable 'swab' function. Usually leave commented unless the testbed diagnoses the contrary. USE_CUSTOM_SWAB Uncomment this if your compiler supports inline USE_INLINE Uncomment this if your compiler doesn't work with fast floor function USE_DEFAULT_FLOOR_CONVERSION Define this one if you are using windows.h in a non-windows environment LCMS_WIN_TYPES_ALREADY_DEFINED Define this one if you want lcms.h just defining public API LCMS_APIONLY 1 - Profile & Transform functions _________________________________ These are the basic functions on making transformations. For simpler operation, you must open two profiles using cmsOpenProfileFromFile(), then create a transform with these opened profiles with cmsCreateTransform(). Using this transform you can color correct your bitmaps by cmsDoTransform(). When you are done you must free the transform AND the profiles by cmsDeleteTransform() and cmsCloseProfile(). _________________________________________________________________________________ cmsHPROFILE cmsOpenProfileFromFile(const char *ICCProfile, const char *sAccess); _________________________________________________________________________________ Opens a profile returning a handle to it. The profile must be contained in a file on disk. Parameters: ICCProfile: File name w/ full path. sAccess: "r" for normal operation, "w" for profile creation Returns: NULL on error, a profile handle on success. Example: void GetProductNameOf(const char *ICMProfileFile) { cmsHPROFILE hProfile hProfile = cmsOpenProfileFromFile(ICMProfileFile, "r"); if (hProfile == NULL) printf("Error!"); else { printf("%s\n", cmsGetProductName(hProfile)); cmsCloseProfile(hProfile); } } _________________________________________________________________________________ cmsHPROFILE cmsOpenProfileFromMem(LPVOID MemPtr, DWORD dwSize); _________________________________________________________________________________ Same as anterior, but profile is contained in memory. Usefull for embedded profiles. MemPtr must point to a buffer of at least dwSize bytes. This buffer must hold a full profile image. Memory must be contiguous. Parameters: MemPtr: Points to a block of contiguous memory containing the profile dwSize: Profile's size measured in bytes. Returns: NULL on error, a profile handle on success. _________________________________________________________________________________ LCMSBOOL cmsCloseProfile(cmsHPROFILE hProfile); _________________________________________________________________________________ Closes a profile handle and frees associated memory. Note that cmsDeleteTransform() does NOT close the involved profiles. You must close any opened profile handle on cleanup. Parameters: hProfile: Handle to an open profile Returns: FALSE on error, TRUE on success Comments: Can return error when creating profile if the profile is not properly flushed to disk. _________________________________________________________________________________ cmsHTRANSFORM cmsCreateTransform(cmsHPROFILE Input, DWORD InputFormat, cmsHPROFILE Output, DWORD OutputFormat, int Intent, DWORD dwFlags); . _________________________________________________________________________________ Creates a transform for translating bitmaps. Parameters: Input, Output: Input, Output profile handles Input, Output format: This value describes how values are to be coded. It is formed by a combination of channels, bitdepths andextra samples. See below. for example: TYPE_BGR_8 : 3 channels of 8 bits, using Windows convention TYPE_RGB_8 : 3 channels of 8 bits per component TYPE_RGB_16 : 3 channels of 16 bits per component TYPE_RGBA_8 : 4 channels, 3 containing RGB of 8 bpc, and one channel of 8 bits holding alpha ... Note than even some Lab and XYZ are defined, these specifiers has nothing to do with colorspaces, but only how data is encoded. The CMM will only check for same colorspace as profile. Intent: The ICC intent to apply. If an appropiate tag for this intent is not found, no error is raised and the intent is reverted to perceptual. See the tutorial for a explanation of intents. INTENT_PERCEPTUAL 0 INTENT_RELATIVE_COLORIMETRIC 1 INTENT_SATURATION 2 INTENT_ABSOLUTE_COLORIMETRIC 3 dwFlags: This value commands on how to handle the whole process. Some or none of this values can be joined via the or | operator. cmsFLAGS_MATRIXINPUT: CLUT ignored on input profile, matrix-shaper used instead (for speed, and debugging purposes) cmsFLAGS_MATRIXOUTPUT: Same as anterior, but for output profile only. cmsFLAGS_MATRIXONLY: Both input and output are forced to matrix-shaper. cmsFLAGS_NOTPRECALC: By default, lcms smelt luts into a device-link CLUT. This speedup whole transform greatly. If you don't wanna this, and wish every value to be translated to PCS and back to output space, include this flag. cmsFLAGS_NULLTRANFORM: Don't transform anyway, only apply pack/unpack routines (usefull to deactivate color correction but keep formatting capabilities) cmsFLAGS_HIGHRESPRECALC: Use 48 points instead of 33 for device-link CLUT precalculation. Not needed but for the most extreme cases of mismatch of "impedance" between profiles. cmsFLAGS_LOWRESPRECALC: Use lower resolution table. cmsFLAGS_GRIDPOINTS(n): You can specify the desired number of gridpoints in devicelink by using this macro in the flags. cmsFLAGS_BLACKPOINTCOMPENSATION: Use BPC algorithm. cmsFLAGS_PRESERVEBLACK: Preserve K channel on CMYK -> CMYK transforms cmsFLAGS_NOTCACHE: Inhibit the 1-pixel built-in cache cmsFLAGS_NOWHITEONWHITEFIXUP: Do NOT fix white-on-white broken profiles cmsFLAGS_NOPRELINEARIZATION: Do NOT use prelinearization tables Returns: NULL on error, a transform handle on success. Comments: This function tries to build a device link profile using the Input and Output profiles. This small time-consuming penalty (3 sec. on a Pentium-100) does accelerate the bitmap transform process greately. You can override this behaviour if you wish, or if you plan to transform only a couple of pixels by using cmsFLAGS_NOTPRECALC on dwFlags parameter. But normally it will be better leave this flag alone. Also, in this function is where you must specify the format of the input and output bitmaps. The InputFormat and OutputFormat parameters are formed by combining several bits: // Format of pixel is defined by one integer, using bits as follows // // TTTTT - Y F P X S EEE CCCC BBB // // T: Pixeltype // F: Flavor 0=MinIsBlack(Chocolate) 1=MinIsWhite(Vanilla) // P: Planar? 0=Chunky, 1=Planar // X: swap 16 bps endianess? // S: Do swap? ie, BGR, KYMC // E: Extra samples // C: Channels (Samples per pixel) // B: Bytes per sample // Y: Swap first - changes ABGR to BGRA and KCMY to CMYK // -: Unused (reserved) lcms.h does include several predefined specifiers, as examples: TYPE_RGB_8 8 bits per sample RGB TYPE_BGR_8 8 bits per sample BGR (Windows Bitmaps are often coded in this way) TYPE_RGB_16 16 bits per sample RGB TYPE_RGBA_8 8 bits per sample RGB plus alpha channel. Alpha is ignored by lcms. TYPE_RGBA_16 16 bits per sample RGB plus alpha. TYPE_XYZ_16 16 bits fixed 15.16 XYZ (used in PCS) TYPE_Lab_8 8 bits per sample Lab TYPE_Lab_16 16 bits per sample Lab TYPE_CMY_8 8 bits per sample CMY TYPE_CMY_16 16 bits per sample CMY TYPE_CMYK_8 8 bits per sample CMYK TYPE_CMYK_16 16 bits per sample CMY You can build your own specifiers if you wish by combining the following macros with the bitwise OR operator | DOSWAP_SH(e) 1 or 0 depending on swap even channels EXTRA_SH(e) up to 7 extra channels CHANNELS_SH(c) up to 4 handled channels BYTES_SH(b) 1 if 16 bits per sample, 0 if 8 bits per sample ENDIAN16_SH(e) 1 if 16 bits samples comes swapped. SWAPFIRST_SH(s) 1 changes ABGR to BGRA and KCMY to CMYK FLAVOR_SH(s) 0 = BlackIsZero (Chocolate) 1=WhiteIsZero (Vanilla, Negative) PLANAR_SH(p) 0 = Chunky, 1=Planar COLORSPACE_SH(s) Available Colorspaces ===================== PT_ANY Don't check colorspace 1 & 2 are reserved PT_GRAY PT_RGB PT_CMY PT_CMYK PT_YCbCr PT_YUV PT_XYZ PT_Lab PT_YUVK PT_HSV PT_HLS PT_Yxy See the lcms.h for more information on how to build format specifiers. _________________________________________________________________________________ cmsHTRANSFORM cdecl cmsCreateProofingTransform(cmsHPROFILE Input, DWORD InputFormat, cmsHPROFILE Output, DWORD OutputFormat, cmsHPROFILE Proofing, int Intent, int ProofingIntent, DWORD dwFlags); _________________________________________________________________________________ Same as cmsCreateTransform(), but including soft-proofing. The obtained transform emulates the device described by the "Proofing" profile. Useful to preview final result whithout rendering to physical medium. Parameters and returns same as anterior, but with the addition of Proofing: a handle to proofing profile. ProofingIntent: Is the intent for translating emulated colors. Default is INTENT_ABSOLUTE_COLORIMETRIC. dwFlags: cmsFLAGS_GAMUTCHECK: Color out of gamut are flagged to a fixed color defined by the function cmsSetAlarmCodes(int r, int g, int b); cmsFLAGS_SOFTPROOFING: (Does need preview tag to work) does emulate the Proofing device. You need to add a combination of these flags to enable any proof! _________________________________________________________________________________ cmsHTRANSFORM cmsCreateMultiprofileTransform(cmsHPROFILE hProfiles[], int nProfiles, DWORD InputFormat, DWORD OutputFormat, int Intent, DWORD dwFlags); _________________________________________________________________________________ User passes in an array of handles to open profiles. The returned handle does "smelt" all profiles in only one devicelink. Following rules should be followed: - Colorspaces must be paired with the exception of Lab/XYZ, that can be interchanged. - Profile must be Matrix-shaper, or hold the apropiate tag, device-to-pcs or pcs-to-device on depending on profile location. - All colorspaces up to 4 (significant) channels can be used anywhere on the chain, Hexachrome separation or more can only appair at last step. This limitation is intended to be solved in future releases. Let's take as example, how to apply a abstract profile into a SRGB image. The chain would be sRGB -> Abstract -> sRGB. So, we would open sRGB and the abstract profile, and fill the array Profiles[0] = hsRGB; Profiles[1] = hAbstract; Profiles[2] = hsRGB; cmsCreateMultiprofileTransform(Profiles, 3, TYPE_RGB_8, TYPE_RGB_8, INTENT_PERCEPTUAL, 0); WARNING: he dE rises with the number of profiles. This can be used, for example, with abstract profiles. For example, abstract profiles can be applied into a typical profile-to-profile color flow to model viewing conditions. Once created, the transform will behave just like any other. _________________________________________________________________________________ void cmsDeleteTransform(cmsHTRANSFORM hTransform); _________________________________________________________________________________ Closes a transform handle and frees associated memory. Parameters: hTransform: The transform handle to be deleted. Comments: This function does NOT free any profiles associated with the transform. Is programmer's responsability to free them. _________________________________________________________________________________ void cmsDoTransform(cmsHTRANSFORM hTransform, LPVOID InputBuffer, LPVOID OutputBuffer, unsigned int Size); _________________________________________________________________________________ This function translates bitmaps according of transform. Format of buffers is described by InputFormat and OutputFormat parameters in function cmsCreateTransform() or cmsCreateProofingTransform() Parameters: hTransform: A handle to a transform describing the translation. InputBuffer: A pointer to a input bitmap OutputBuffer: A pointer to a output bitmap. Size: the number of PIXELS to be transformed. Comments: Windows, stores the bitmaps in a particular way... for speed purposes, does align the scanlines to doubleword boundaries, so a bitmap has in windows always a size multiple of 4. This is ok, since no matter if you waste a couple of bytes, but if you call cmsDoTransform() and passes it WHOLE image, lcms doesn't know nothing about this extra padding bytes. So, it assumes that you are passing a block of BGR triplets with no alignment at all. This result in a strange looking "lines" in obtained bitmap. The solution most evident is to convert scanline by scanline instead of whole image. This is as easy as to add a for() loop, and the time penalty is so low that is impossible to detect. _________________________________________________________________________________ void cmsChangeBuffersFormat(cmsHTRANSFORM hTransform, DWORD dwInputFormat, DWORD dwOutputFormat) _________________________________________________________________________________ This function does change the encoding of buffers in a yet-existing transform. Parameters: hTransform: A handle to the transform. Input, Output format: This value describes how values are to be coded. It is formed by a combination of channels, bitdepths andextra samples. See cmsCreateTransform for more info. Notes: Colorspace is *not* checked _________________________________________________________________________________ cmsHPROFILE cmsTransform2DeviceLink(cmsHTRANSFORM hTransform, DWORD dwFlags); _________________________________________________________________________________ Generates a device-link profile from a transform. This profile can then be used by any other function accepting profile handle, or be saved on disk by _cmsSaveProfile(). See icclink.c for a sample. Parameters: hTransform: A handle to the transform. Flags: cmsFLAGS_GUESSDEVICECLASS: Mark the profile profile class "guessing" from input & output colorspaces. cmsFLAGS_HIGHRESPRECALC: Use 48 points instead of 33 for device-link CLUT precalculation. Not needed but for the most extreme cases of mismatch of "impedance" between profiles. cmsFLAGS_LOWRESPRECALC: Use lower resolution table. cmsFLAGS_GRIDPOINTS(n): You can specify the desired number of gridpoints in devicelink by using this macro in the flags. cmsFLAGS_BLACKPOINTCOMPENSATION: Use BPC algorithm. cmsFLAGS_PRESERVEBLACK: Preserve K channel on CMYK -> CMYK transforms cmsFLAGS_NOTCACHE: Inhibit the 1-pixel built-in cache cmsFLAGS_NOWHITEONWHITEFIXUP: Do NOT fix white-on-white broken profiles cmsFLAGS_NOPRELINEARIZATION: Do NOT use prelinearization tables 2 - Information functions _________________________________________________________________________________ These functions are intended for identify profiles. Its main use if for building user interfaces. _________________________________________________________________________________ void cmsSetLanguage(int LanguageCode, int CountryCode); _________________________________________________________________________________ This function applies only to v4 profiles, which may have multilocalized strings for information functions. Using cmsSetLanguage(), you set the preferred language and country in what you want the information. All strings are searched for an exact match of language and country. In none found, then another search is done for same language, ignoring country. If no matching is found, the first string in table is returned. Parameters: LanguageCode: first name language code from ISO-639. http://lcweb.loc.gov/standards/iso639-2/iso639jac.html CountryCode: first name region code from ISO-3166. http://www.iso.ch/iso/en/prods-services/iso3166ma/index.html _________________________________________________________________________________ const char* cmsTakeProductName(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns a pointer to a string containing the product name. The string is holded in a static buffer that is overwritten in every call to this function. Parameters: hProfile: Handle to an open profile _________________________________________________________________________________ const char* cmsTakeProductDesc(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns a pointer to a string containing the product Description. The string is holded in a static buffer that is overwritten in every call to this function. Parameters: hProfile: Handle to an open profile Returns: Product description in a static buffer overwritten in each call to this function. _________________________________________________________________________________ const char* cmsTakeProductInfo(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns a pointer to a string containing additional info about hProfile. The string is holded in a static buffer overwritten in each call to this function. Parameters: hProfile: Handle to an open profile Returns: Product info in a static buffer overwritten in each call to this function. _________________________________________________________________________________ const char* cmsTakeManufacturer(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns a pointer to a string containing uncooked info about manufacturer. The string is holded in a static buffer overwritten in each call to this function. Parameters: hProfile: Handle to an open profile Returns: Manufacturer in a static buffer overwritten in each call to this function. _________________________________________________________________________________ const char* cmsTakeModel(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns a pointer to a string containing uncooked info about model. The string is holded in a static buffer overwritten in each call to this function. Parameters: hProfile: Handle to an open profile Returns: Model description in a static buffer overwritten in each call to this function. _________________________________________________________________________________ const char* cmsTakeCopyright(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns a pointer to a string containing uncooked info about copyright. The string is holded in a static buffer overwritten in each call to this function. Parameters: hProfile: Handle to an open profile Returns: Copyright info in a static buffer overwritten in each call to this function. _________________________________________________________________________________ icColorSpaceSignature cmsGetPCS(cmsHPROFILE hProfile) _________________________________________________________________________________ This function returns the PCS used by the hProfile, using the ICC convention. Parameters: hProfile: Handle to an open profile Returns: The PCS of the profile _________________________________________________________________________________ icColorSpaceSignature cmsGetColorSpace(cmsHPROFILE hProfile) _________________________________________________________________________________ This function returns the Color space used by the hProfile, using the ICC convention. Parameters: hProfile: Handle to an open profile Returns: The color space of the profile _________________________________________________________________________________ DWORD cmsGetProfileICCversion(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns the ICC version as stated in the header of the profile. Examples: V2 profiles: 0x2000000 V4 profiles: 0x4000000 Parameters: hProfile: Handle to an open profile Returns: The profile version stamp _________________________________________________________________________________ icProfileClassSignature cmsGetDeviceClass(cmsHPROFILE hProfile) _________________________________________________________________________________ This function returns the Device class of hProfile, using the ICC convention. Parameters: hProfile: Handle to an open profile Returns: The device class of the profile _________________________________________________________________________________ LCMSBOOL cmsTakeMediaWhitePoint(LPcmsCIEXYZ Dest, cmsHPROFILE hProfile); _________________________________________________________________________________ This function takes the white point of hProfile. Parameters: Dest: a pointer to an cmsCIEXYZ struct that will hold the media white point hProfile: Handle to an open profile Returns: FALSE on error, TRUE on success _________________________________________________________________________________ LCMSBOOL cmsTakeMediaBlackPoint(LPcmsCIEXYZ Dest, cmsHPROFILE hProfile); _________________________________________________________________________________ This function takes the contents of black point tag of hProfile if present. Parameters: Dest: a pointer to an cmsCIEXYZ struct that will hold the media black point. hProfile: Handle to an open profile Returns: FALSE on error, TRUE on success NOTES: Most profiles have garbage in this tag, for a suitable black point detection use cmsDetectBlackPoint() instead. _________________________________________________________________________________ LCMSBOOL cmsTakeIluminant(LPcmsCIEXYZ Dest, cmsHPROFILE hProfile); _________________________________________________________________________________ This function takes the value of PCS illuminant of hProfile. Parameters: hProfile: Handle to an open profile Dest: a pointer to an cmsCIEXYZ struct that will hold the illuminant white point Returns: FALSE on error, TRUE on success Notes: ICC states that profile illuminants MUST be D50. However, in real world, each manufacturer uses an illuminant value that differs slightly of D50. lcms forces it to D50 to prevent errors. _________________________________________________________________________________ LCMSBOOL cmsTakeColorants(LPcmsCIEXYZTRIPLE Dest, cmsHPROFILE hProfile); _________________________________________________________________________________ This function takes the value of colorant matrix of hProfile if present. Parameters: hProfile: Handle to an open profile Dest: a pointer to an cmsCIEXYZ struct that will hold the illuminant white point Returns: FALSE on error, TRUE on success Notes: Some profiles includes colorants even if a CLUT is already present. Often this colorants are private values, or a way to allow the profile operate in reverse direction. _________________________________________________________________________________ icInt32Number cmsGetTagCount(cmsHPROFILE hProfile); _________________________________________________________________________________ Return number of tags contained in a profile Parameters: hProfile: Handle to an open profile Returns: Number of tags _________________________________________________________________________________ icTagSignature cmsGetTagSignature(cmsHPROFILE hProfile, icInt32Number n); _________________________________________________________________________________ Enumerates tags in a profile Parameters: hProfile: Handle to an open profile n : Tag ordinal Returns: Tag signature _________________________________________________________________________________ LCMSBOOL cmsIsTag(cmsHPROFILE hProfile, icTagSignature sig); _________________________________________________________________________________ Tests whatever a particular tag is present in hProfile. Parameters: hProfile: Handle to an open profile sig: a tag signature Returns: FALSE if not present, TRUE if tag is found _________________________________________________________________________________ int cmsTakeRenderingIntent(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns the rendering intent field of the header. This field is informative and not used by the CMM for any purpose. Parameters: hProfile: Handle to an open profile Returns: one of the following values: INTENT_PERCEPTUAL 0 INTENT_RELATIVE_COLORIMETRIC 1 INTENT_SATURATION 2 INTENT_ABSOLUTE_COLORIMETRIC 3 _________________________________________________________________________________ int cmsTakeHeaderFlags(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns the flags field of the ICC profile header. These are flags to indicate various hints for the CMM such as distributed processing and caching options. The least significant 16 bits are reserved for the ICC. Currently (v4.2) there are only two ICC flags defined: Bit Meaning --- ------------------------------------------------------------- 0 Embedded Profile (0 if not embedded, 1 if embedded in file) 1 Profile cannot be used independently from the embedded color data (set to 1 if true, 0 if false) Parameters: hProfile: Handle to an open profile Returns: The header flags _________________________________________________________________________________ int cmsTakeHeaderAttributes(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns the attributes field of the ICC profile header. The device attributes field shall contain flags used to identify attributes unique to the particular device setup for which the profile is applicable. Currently (v4.2) there are only two ICC attributes defined: Bit Meaning --- ------------------------------------------------------------- 0 0=icReflective 1=icTransparency 1 0=icGlossy 1=icMatte Parameters: hProfile: Handle to an open profile Returns: The header attributes _________________________________________________________________________________ LCMSBOOL cmsIsIntentSupported(cmsHPROFILE hProfile, int Intent, int UsedDirection); _________________________________________________________________________________ This one helps on inquiring if a determinate intent is supported by an opened profile. You must give a handle to profile, the intent and a third parameter specifying how the profile would be used. The function does return TRUE if intent is supported or FALSE if not. If the intent is not supported, lcms will use default intent (usually perceptual). Parameters: hProfile: Handle to an open profile Intent: one of the following values: INTENT_PERCEPTUAL 0 INTENT_RELATIVE_COLORIMETRIC 1 INTENT_SATURATION 2 INTENT_ABSOLUTE_COLORIMETRIC 3 Direction: LCMS_USED_AS_INPUT 0 LCMS_USED_AS_OUTPUT 1 LCMS_USED_AS_PROOF 2 Returns: TRUE if intent is supported or FALSE if not. If the intent is not supported, lcms will use default intent (usually perceptual). _________________________________________________________________________________ LCMSBOOL cmsTakeCharTargetData(cmsHPROFILE hProfile, char** Data, size_t* len); _________________________________________________________________________________ Retrieves the target data the profiler has used to build the profile. Usage of this tag is optional. The lprof profiles does store such information when "verbose" mode is selected. Parameters: hProfile: Handle to an open profile Data: Pointer to a pointer to a bite block. This function allocates this block by calling malloc(). User is responsible of free it after use. size: Pointer to a size_t variable holding the size of datablock. Returns: TRUE on success, FALSE on error or if the profile has not such tag. Example: char* TargetData; size_t len; cmsTakeCharTargetData(hProfile, &Data, &len); ... do whatsever with Data... free(Data); _________________________________________________________________________________ const LPBYTE cmsTakeProfileID(cmsHPROFILE hProfile); _________________________________________________________________________________ Returns the 16-bytes profile ID (version 4 only). The ProfileID is holded in a static buffer overwritten in each call to this function. Parameters: hProfile: Handle to an open profile Returns: A pointer to a static buffer holding the 16 bytes ID. This buffer is overwritten in each function call. _________________________________________________________________________________ LCMSBOOL _cmsIsMatrixShaper(cmsHPROFILE hProfile); _________________________________________________________________________________ Tests whatever a particular profile is implemented as Matrix-shaper- Parameters: hProfile: Handle to an open profile Returns: TRUE or FALSE about profile being implemented as matrix-shaper _________________________________________________________________________________ void cmsSetAlarmCodes(int r, int g, int b) _________________________________________________________________________________ Used to establish the out-of-gamut alarm color. This color will replace all out-of-gamut colors if sFLAGS_GAMUTCHEK is used in dwFlags parameter. See cmsCreateTransform() _________________________________________________________________________________ void _cmsSetLUTdepth(cmsHPROFILE hProfile, int depth); _________________________________________________________________________________ INTERNAL, USE WITH CAUTION. Used to inform the profile writting logic that all LUTS should be written in 8-bit resolution. lcms currently allows to write profiles with same resolution in all LUTS. Incoming versions may fix that. Parameters: hProfile: Handle to an open profile depth: either 8 or 16 _________________________________________________________________________________ LCMSBOOL _cmsSaveProfile(cmsHPROFILE hProfile, const char* FileName); LCMSBOOL _cmsSaveProfileToMem(cmsHPROFILE hProfile, void *MemPtr, size_t* BytesNeeded); _________________________________________________________________________________ INTERNAL, USE WITH CAUTION. Dumps the contents of a profile FULLY GENERATED BY USING VIRTUAL PROFILES to disk or memory. Disk based profiles are not suitable for these functions. DEPRECATED, use cmsOpenProfileFromFile() with a "w" as access mode instead. _________________________________________________________________________________ 3 - On-the-fly (virtual) profile creation functions _________________________________________________________________________________ These function gives the ability of create virtual profiles. These profiles are often used in modelling monitors, but can also be used as any input or output device. Once created, you can use the profile handle like another file-based profile. _________________________________________________________________________________ cmsHPROFILE cmsCreateGrayProfile(LPcmsCIExyY WhitePoint, LPGAMMATABLE TransferFunction) _________________________________________________________________________________ Creates a grayscale virtual profile based on white point and transfer tables. Parameters: White point: You can specify chromacity of white point, or use cmsWhitePointFromTemp() to generate the white point from temperature. Gamma tables: You can directly specify tables or use the gamma handling functions for obtaining these tables _________________________________________________________________________________ cmsHPROFILE cmsCreateRGBProfile(LPcmsCIExyY WhitePoint, LPcmsCIExyYTRIPLE Primaries, LPGAMMATABLE TransferFunction[3]) _________________________________________________________________________________ Creates a virtual profile based in primaries, white point and transfer tables. Parameters: White point: You can specify chromacity of white point, or use cmsWhitePointFromTemp() to generate the white point from temperature. Primaries: The primaries (the TRUE primaries, not the colorants) of the device. Gamma tables: You can directly specify tables or use the gamma handling functions for obtaining these tables _________________________________________________________________________________ cmsHPROFILE cmsCreateLinearizationDeviceLink(icColorSpaceSignature ColorSpace, LPGAMMATABLE TransferFunctions[]); _________________________________________________________________________________ Creates a specialized devicelink, operating in space "ColorSpace". This devicelink has only linearization tables. Usefull for embedding gamma/brightness/contrast controls in a multiprofile transform. TransferFunctions[] must contain as many curves as components has the target color space. For example, RGB must be 3 curves. CMYK needs 4 curves. _________________________________________________________________________________ cmsHPROFILE LCMSEXPORT cmsCreateInkLimitingDeviceLink(icColorSpaceSignature ColorSpace, double Limit) _________________________________________________________________________________ Creates a specialized devicelink, operating in space "ColorSpace". This devicelink handles ink-limiting feature. Useful for RIP construction and other goodies Parameters: hTransform: A handle to the transform. Limit: The amount of ink-limit, in pertentage. Allowable values are from 0% to 400% Notes: Currently only works on CMYK, but Hexachrome support is expected in future revisions. _________________________________________________________________________________ cmsHPROFILE cmsCreateBCHSWabstractProfile(int nLUTPoints, double Bright, double Contrast, double Hue, double Saturation, int TempSrc, int TempDest); _________________________________________________________________________________ Creates a abstract devicelink operating in Lab for Bright/Contrast/Hue/Saturation and white point translation. White points are specified as temperatures ºK Parameters: int nLUTPoints : Resulting CLUT resolution double Bright : Bright increment. May be negative double Contrast : Contrast increment. May be negative. double Hue : Hue displacement in degree. double Saturation : Saturation increment. May be negative int TempSrc : Source white point temperature int TempDest : Destination white point temperature. Renges: Bright: _________________________________________________________________________________ 4 - Built-In profiles _________________________________________________________________________________ These are standard profiles optimized for speed. _________________________________________________________________________________ cmsHPROFILE cmsCreateLabProfile(LPcmsCIExyY WhitePoint); _________________________________________________________________________________ Creates a virtual profile of CIE Lab. If WhitePoint is NULL, then D50 is assumed. It uses v2 PCS encoding. _________________________________________________________________________________ cmsHPROFILE cmsCreateLab4Profile(LPcmsCIExyY WhitePoint); _________________________________________________________________________________ Creates a virtual profile of CIE Lab operanting in v4 PCS encoding. If WhitePoint is NULL, then D50 is assumed. _________________________________________________________________________________ cmsHPROFILE cmsCreateXYZProfile(void); _________________________________________________________________________________ Creates a virtual XYZ profile (Assumes D50) _________________________________________________________________________________ cmsHPROFILE cmsCreate_sRGBProfile(void); _________________________________________________________________________________ Creates a virtual profile of sRGB standard colorspace. _________________________________________________________________________________ 5 - White point _________________________________________________________________________________ _________________________________________________________________________________ LCMSBOOL cmsWhitePointFromTemp(int TempK, LPcmsCIExyY WhitePoint); _________________________________________________________________________________ Obtains the chromaticity of white point based on temperature §K Parameters: TempK: Temperature in §K Returns: FALSE on error, TRUE on success _________________________________________________________________________________ LCMSAPI LCMSBOOL LCMSEXPORT cmsAdaptToIlluminant(LPcmsCIEXYZ Result, LPcmsCIEXYZ SourceWhitePt, LPcmsCIEXYZ Illuminant, LPcmsCIEXYZ Value); _________________________________________________________________________________ Provides a model-dependent chromatic adaptation between two illuminants, actually it uses a Von-Kries approximation of Bradford, using the Lam-Rigg cone responses. It Is under consideration to be replaced for a more proper model like CIECAM97s in futures versions. Parameters: Result: Points to resulting XYZ color SourceWhitePoint: original white point Illuminant: adapting illuminant Value: the original color Returns: FALSE on error, TRUE on success _________________________________________________________________________________ double cmsSetAdaptationState(double d); _________________________________________________________________________________ Specifies adaptation state of observer for V4 absolute colorimetric transforms. Only two values are implemented: d = 0: No adaptation d = 1: Observer is fully adapted _________________________________________________________________________________ 6 - Gamma handling functions _________________________________________________________________________________ This is the struct of a gamma table (or transfer function) typedef struct { int nEntries; WORD GammaTable[1]; } GAMMATABLE, FAR* LPGAMMATABLE; That is, first it comes a 32 integer for entry count, followed of a variable number of words describing the table. The easiest way to generate a gamma table is to use the following function _________________________________________________________________________________ LPGAMMATABLE cmsBuildGamma(int nEntries, double Gamma); _________________________________________________________________________________ Allocates an fill a table describing generic gamma. You must specify the number of entries your table will consist of, and the float value for gamma. _________________________________________________________________________________ LPGAMMATABLE cmsBuildParametricGamma(int nEntries, int Type, double Params[]); _________________________________________________________________________________ Does build a parametric curve based on parameters. Params[] does contain Gamma, a, b, c, d, e, f Type 1 : X = Y ^ Gamma | Gamma = Params[0] Type 2 : CIE 122-1966 Y = (aX + b)^Gamma | X >= -b/a Y = 0 | else Type 3: IEC 61966-3 Y = (aX + b)^Gamma | X <= -b/a Y = c | else Type 4: IEC 61966-2.1 (sRGB) Y = (aX + b)^Gamma | X >= d Y = cX | X < d Type 5: Y = (aX + b)^Gamma + e | X <= d Y = cX + f | else Giving negative values for Type does result in reversed curve. _________________________________________________________________________________ LPGAMMATABLE cmsAllocGamma(int nEntries); _________________________________________________________________________________ Allocates space for a gamma table, memory is unitialized. _________________________________________________________________________________ void cmsFreeGamma(LPGAMMATABLE Gamma); _________________________________________________________________________________ Frees a gamma table _________________________________________________________________________________ LPGAMMATABLE cmsReverseGamma(int nResultSamples, LPGAMMATABLE InGamma); _________________________________________________________________________________ Reverses a gamma table resampling it in a new table. This function reverses the gamma table if it can be done. lcms does not detect whatever a non-monotonic function is given, so wrong input can result in ugly results: not to be a problem since "normal" gamma curves are not collapsing inputs at same output value. The new curve will be resampled to nResultSamples entries. _________________________________________________________________________________ LPGAMMATABLE cmsJoinGamma(LPGAMMATABLE InGamma, LPGAMMATABLE OutGamma); _________________________________________________________________________________ Obtains a table joining two tables, one as input and other as output. Output table is reversed and then composited with input gamma. This will let you to "refine" the generic gamma for monitors (2.1 or 2.2 are usual values) to match viewing conditions of more or less background light. Note that this function uses TABULATED functions, so very exotic curves can be obtained by combining transfer functions with reversed gamma curves. Normally there is no need of worry about such gamma manipulations, but the functionality is here if you wish to use. _________________________________________________________________________________ LCMSBOOL cmsSmoothGamma(LPGAMMATABLE Tab, double lambda); _________________________________________________________________________________ Does smooth the curve contained into Tab. Smooth curves does work better and more pleasant to eye. Parameters: Tab: Table to be smoothed lambda: The smoothing factor. 0..500 is the working range. Returns: TRUE on success. FALSE on error _________________________________________________________________________________ double cmsEstimateGamma(LPGAMMATABLE t); double cmsEstimateGammaEx(LPWORD Table, int nEntries, double Thereshold); _________________________________________________________________________________ Returns a numerical estimation of the apparent gamma on the given table. _________________________________________________________________________________ LPGAMMATABLE cmsReadICCGamma(cmsHPROFILE hProfile, icTagSignature sig); LPGAMMATABLE cmsReadICCGammaReversed(cmsHPROFILE hProfile, icTagSignature sig); int cmsReadICCText(cmsHPROFILE hProfile, icTagSignature sig, char *Text); int cmsReadICCTextEx(cmsHPROFILE hProfile, icTagSignature sig, char *Text, size_t size); _________________________________________________________________________________ _________________________________________________________________________________ LPcmsSEQ cmsReadProfileSequenceDescription(cmsHPROFILE hProfile); void cmsFreeProfileSequenceDescription(LPcmsSEQ pseq); _________________________________________________________________________________ Reads and free profile sequence description structure _________________________________________________________________________________ void cmsSetUserFormatters(cmsHTRANSFORM hTransform, DWORD dwInput, cmsFORMATTER Input, DWORD dwOutput, cmsFORMATTER Output); void cmsGetUserFormatters(cmsHTRANSFORM hTransform, LPDWORD InputFormat, cmsFORMATTER* Input, LPDWORD OutputFormat, cmsFORMATTER* Output); _________________________________________________________________________________ _________________________________________________________________________________ 7 - Error handling _________________________________________________________________________________ _________________________________________________________________________________ void cmsErrorAction(int nAction) _________________________________________________________________________________ Tells lcms how to react if an error is raised. Parameters: nAction: can be one of these: LCMS_ERROR_ABORT Aborts whole application LCMS_ERROR_SHOW Displays a message, but does not abort application LCMS_ERROR_IGNORE Does not show any message, however, operation is aborted. _________________________________________________________________________________ void cmsSignalError(int ErrorCode, const char *ErrorText, ...) _________________________________________________________________________________ This is the default error handler. If you are using lcms as a static library, you can replace it by one of your own. Parameters: ErrorCode: a number for coding error (with not meaning by now) ErrorText: a format specifier describing the error ... : additional parameters needed by ErrorText, in a printf like fashion. _________________________________________________________________________________ void cmsSetErrorHandler(cmsErrorHandlerFunction Fn); _________________________________________________________________________________ This function sets an user-defined error handler. The error handler must be defined as: int ErrorHandlerFunction(int ErrorCode, const char *ErrorText); ErrorCode can be one of the following values: LCMS_ERRC_WARNING 0x1000 LCMS_ERRC_RECOVERABLE 0x2000 LCMS_ERRC_ABORTED 0x3000 ErrorText is a text holding an english description of error. _________________________________________________________________________________ 8 - Conversion functions _________________________________________________________________________________ These functions can be used to convert from several colorimetric spaces and to/from fixed encoding in spaces XYZ and Lab used by profiles. _________________________________________________________________________________ LCMSAPI void LCMSEXPORT cmsXYZ2xyY(LPcmsCIExyY Dest, CONST LPcmsCIEXYZ Source); LCMSAPI void LCMSEXPORT cmsxyY2XYZ(LPcmsCIEXYZ Dest, CONST LPcmsCIExyY Source); _________________________________________________________________________________ Does convert form/to XYZ Color Space to xyY color space Parameters: Dest, Source: points to vectors to convert _________________________________________________________________________________ void cmsXYZ2Lab(LPcmsCIEXYZ WhitePoint, LPcmsCIELab Lab, const LPcmsCIEXYZ xyz); void cmsLab2XYZ(LPcmsCIEXYZ WhitePoint, LPcmsCIEXYZ xyz, const LPcmsCIELab Lab); _________________________________________________________________________________ Does convert from/to XYZ Color Space to CIE L a* b* Color Space Parameters: xyz, Lab : Pointers to values WhitePoint: Pointer to media white. If NULL, the D50 is assumed. _________________________________________________________________________________ void cmsLabEncoded2Float(LPcmsCIELab Lab, const WORD wLab[3]); void cmsFloat2LabEncoded(WORD wLab[3], const LPcmsCIELab Lab); _________________________________________________________________________________ Does convert form/to the encoded notation of Lab pcs to floating point. Parameters: wLab, Lab : Pointers to values _________________________________________________________________________________ void cmsXYZEncoded2Float(LPcmsCIEXYZ fxyz, const WORD XYZ[3]); void cmsFloat2XYZEncoded(WORD XYZ[3], const LPcmsCIEXYZ fXYZ); _________________________________________________________________________________ Does convert form/to the encoded notation of XYZ pcs to floating point. Parameters: fxyz, XYZ : Pointers to values _________________________________________________________________________________ void cmsLab2LCh(LPcmsCIELCh LCh, const LPcmsCIELab Lab); void cmsLCh2Lab(LPcmsCIELab Lab, const LPcmsCIELCh LCh); _________________________________________________________________________________ Does convert between polar/rectangulat form of CIE L*a*b* L = L C = sqrt(a*a+b*b) h = atan(b/a) Where C=colorfulness and h=hue. Parameters: Lab, LCh : Pointers to values _________________________________________________________________________________ double cmsDeltaE(LPcmsCIELab Lab1, LPcmsCIELab Lab2); _________________________________________________________________________________ Computes the dE between two Lab values. The formula is dE = sqrt (dL^2 + da^2 + db^2) Parameters: Lab1, Lab2: Points to the Lab values. Returns: The dE. If any Lab is negative, or with L>100 it returns 65535. _________________________________________________________________________________ double cmsCIE94DeltaE(LPcmsCIELab Lab1, LPcmsCIELab Lab2); double cmsBFDdeltaE(LPcmsCIELab Lab1, LPcmsCIELab Lab2); double cmsCMCdeltaE(LPcmsCIELab Lab1, LPcmsCIELab Lab2); double cmsCIE2000DeltaE(LPcmsCIELab Lab1, LPcmsCIELab Lab2, double Kl, double Kc, double Kh); _________________________________________________________________________________ Several additional error measurement systems. _________________________________________________________________________________ void cmsClampLab(LPcmsCIELab Lab, double amax, double amin, double bmax, double bmin); _________________________________________________________________________________ Clamps carefully a Lab value, keeping hue constant. L is unchanged and not used. The gamut boundaries are given by the rectangle (amin, bmin) - (amax, bmax) if Lab value is inside gamut, this function don't touch anything, if outside, converts to LCh, and keeping h constant, reduce C until inside gamut. _________________________________________________________________________________ LCMSAPI icColorSpaceSignature LCMSEXPORT _cmsICCcolorSpace(int OurNotation); LCMSAPI int LCMSEXPORT _cmsLCMScolorSpace(icColorSpaceSignature ProfileSpace); LCMSAPI int LCMSEXPORT _cmsChannelsOf(icColorSpaceSignature ColorSpace); _________________________________________________________________________________ _________________________________________________________________________________ 9 - CIECAM97s/CIECAM02 _________________________________________________________________________________ The model input data are the adapting field luminance in cd/m2 (normally taken to be 20% of the luminance of white in the adapting field), La , the relative tristimulus values of the stimulus, XYZ, the relative tristimulus values of white in the same viewing conditions, "whitePoint", and the relative luminance of the background, Yb . Relative tristimulus values should be expressed on a scale from Y = 0 for a perfect black to Y = 100 for a perfect reflecting diffuser. All CIE tristimulus values are obtained using the CIE 1931 Standard Colorimetric Observer (2°). typedef struct { cmsCIEXYZ whitePoint; // The media white in XYZ double Yb; double La; int surround; double D_value; } cmsViewingConditions, FAR* LPcmsViewingConditions; surround can be one of these #define AVG_SURROUND 1 #define DIM_SURROUND 2 #define DARK_SURROUND 3 D_value (adaptation degree) is any value between 0 and 1, and additionally: #define D_CALCULATE (-1) // Calculate D #define D_CALCULATE_DISCOUNT (-2) // Calculate w/ partial discounting _________________________________________________________________________________ HANDLE cmsCIECAM97sInit(LPcmsViewingConditions pVC)/cmsCIECAM02Init _________________________________________________________________________________ Does init the model. It returns a handle for further reference Parameters: pVC: points to a cmsViewingConditions struct holding viewing condition parameters Returns: A handle to a model instance, or NULL if error. _________________________________________________________________________________ void cmsCIECAM97sDone(HANDLE hModel)/cmsCIECAM02Done _________________________________________________________________________________ Terminates a model Parameters: hModel: A handle to the model instance to terminate. _________________________________________________________________________________ void cmsCIECAM97sForward(HANDLE hModel, LPcmsCIEXYZ pIn, LPcmsJCh pOut)/ cmsCIECAM02Forward _________________________________________________________________________________ Model forward. Transforms from XYZ to JCh. Parameters: hModel: A handle to the model instance pIn, POut: Pointers to values _________________________________________________________________________________ void cmsCIECAM97sReverse(HANDLE hModel, LPcmsJCh pIn, LPcmsCIEXYZ pOut)/ cmsCIECAM02Reverse _________________________________________________________________________________ Model reverse. Transforms from JCh to XYZ. Parameters: hModel: A handle to the model instance pIn, POut: Pointers to values _________________________________________________________________________________ 10 - Profile creation functions _________________________________________________________________________________ _________________________________________________________________________________ void cmsSetDeviceClass(cmsHPROFILE hProfile, icProfileClassSignature sig); _________________________________________________________________________________ Does set device class signature in profile header _________________________________________________________________________________ void cmsSetColorSpace(cmsHPROFILE hProfile, icColorSpaceSignature sig); _________________________________________________________________________________ Does set colorspace signaure in profile header _________________________________________________________________________________ void cmsSetPCS(cmsHPROFILE hProfile, icColorSpaceSignature pcs); _________________________________________________________________________________ Does set PCS signature in profile header _________________________________________________________________________________ void cmsSetRenderingIntent(cmsHPROFILE hProfile, int RenderingIntent); _________________________________________________________________________________ Sets the rendering intent in profile header _________________________________________________________________________________ void cmsSetProfileID(cmsHPROFILE hProfile, LPBYTE ProfileID); _________________________________________________________________________________ Sets the profile ID in profile header (ver 4 only) _________________________________________________________________________________ void cmsSetHeaderFlags(cmsSetHeaderFlags(cmsHPROFILE hProfile, DWORD Flags) _________________________________________________________________________________ Does set flags in profile header _________________________________________________________________________________ void cmsSetHeaderAttributes(cmsSetHeaderFlags(cmsHPROFILE hProfile, DWORD Flags) _________________________________________________________________________________ Does set attribute flags in profile header _________________________________________________________________________________ LCMSBOOL cmsAddTag(cmsHPROFILE hProfile, icTagSignature sig, void* data); _________________________________________________________________________________ Adds a new tag to a profile. Supported tags are: Signature Expected data type ================= ================== icSigCharTargetTag const char* icSigCopyrightTag const char* icSigProfileDescriptionTag const char* icSigDeviceMfgDescTag const char* icSigDeviceModelDescTag const char* icSigRedColorantTag LPcmsCIEXYZ icSigGreenColorantTag LPcmsCIEXYZ icSigBlueColorantTag LPcmsCIEXYZ icSigMediaWhitePointTag LPcmsCIEXYZ icSigMediaBlackPointTag LPcmsCIEXYZ icSigRedTRCTag LPGAMMATABLE icSigGreenTRCTag LPGAMMATABLE icSigBlueTRCTag LPGAMMATABLE icSigGrayTRCTag LPGAMMATABLE icSigAToB0Tag LPLUT icSigAToB1Tag LPLUT icSigAToB2Tag LPLUT icSigBToA0Tag LPLUT icSigBToA1Tag LPLUT icSigBToA2Tag LPLUT icSigGamutTag LPLUT icSigPreview0Tag LPLUT icSigPreview1Tag LPLUT icSigPreview2Tag LPLUT icSigChromaticityTag LPcmsCIExyYTRIPLE icSigNamedColor2Tag LPcmsNAMEDCOLORLIST icSigColorantTableTag LPcmsNAMEDCOLORLIST icSigColorantTableOutTag LPcmsNAMEDCOLORLIST icSigCalibrationDateTimeTag const struct tm* _________________________________________________________________________________ 11 - LUT manipulation _________________________________________________________________________________ This is the pipeline LUT is implementing [Mat] -> [L1] -> [Mat3] -> [Ofs3] -> [L3] -> [CLUT] -> [L4] -> [Mat4] -> [Ofs4] -> [L2] _________________________________________________________________________________ LPLUT cmsAllocLUT(void); _________________________________________________________________________________ Does allocate an empty LUT. Input is passed transparently to output by default Returns: A handle to a new LUT, or NULL if error. _________________________________________________________________________________ LPLUT cmsDupLUT(LPLUT Orig); _________________________________________________________________________________ Duplicates a LUT. Returns: A handle to a new LUT, or NULL if error. _________________________________________________________________________________ LPLUT cmsAllocLinearTable(LPLUT NewLUT, LPGAMMATABLE Tables[], int nTable); _________________________________________________________________________________ Does include a prelinearization tables set into a LUT Parameters: NewLUT: The target LUT Tables[]: A set of tables to be set nTable: Identificates the position of tables in pipeline 1 - Prelinearization 2 - Postlinearization 3 - L3 4 - L4 Values 3 and 4 are reserved for v4 profiles _________________________________________________________________________________ LPLUT cmsAlloc3DGrid(LPLUT Lut, int clutPoints, int inputChan, int outputChan); _________________________________________________________________________________ Allocates an empty 3D CLUT table. Parameters: Lut: The target LUT clutPoints: The points number of a side of the (hyper)cube inputChan, outputChan: The channels count Returns: A handle to the LUT, or NULL if error. _________________________________________________________________________________ void cmsFreeLUT(LPLUT Lut); _________________________________________________________________________________ Free any used memory. After this call the LUT is not longer valid Parameters: Lut: The target LUT _________________________________________________________________________________ void cmsEvalLUT(LPLUT Lut, WORD In[], WORD Out[]); _________________________________________________________________________________ Evaluates a LUT, giving In[] values. Returns Out[] values. Parameters: Lut: The target LUT In: Input Values Out: Output Values _________________________________________________________________________________ LPLUT cmsSetMatrixLUT(LPLUT Lut, LPMAT3 M); _________________________________________________________________________________ Provided for backwards compatibility sake. Sets the 'Mat' Matrix in the LUT pipeline _________________________________________________________________________________ LPLUT cmsSetMatrixLUT4(LPLUT Lut, LPMAT3 M, LPVEC3 off, DWORD dwFlags); _________________________________________________________________________________ Set a matrix in V4 style. Flags defines the location in the LUT pipeline: LUT_HASMATRIX: Mat LUT_HASMATRIX3: Mat3 LUT_HASMATRIX4: Mat4 _________________________________________________________________________________ LPLUT cmsReadICCLut(cmsHPROFILE hProfile, icTagSignature sig); _________________________________________________________________________________ Does retrive a LUT from a profile handle. Parameters: hProfile: a handle to a open profile sig: The tag signature Returns: A pointer to newly created LUT on success NULL on error _________________________________________________________________________________ int cmsSample3DGrid(LPLUT Lut, _cmsSAMPLER Sampler, LPVOID Cargo, DWORD dwFlags); _________________________________________________________________________________ Builds the CLUT table by calling repeatly a supplied callback function typedef int (* _cmsSAMPLER)(register WORD In[], register WORD Out[], register LPVOID Cargo); The programmer has to write a callback function. This function should calculate Out values given a In[] set. For example, if we want a LUT to invert channels, a sampler could be: int InvertSampler(register WORD In[], register WORD Out[], register LPVOID Cargo) { for (i=0; i < 3; i++) Out[i] = ~ In[i]; return 0; } cmsSample3DGrid does call this function to build the CLUT. Pre/post linearization tables may be taken into account across flags parameter Flags Meaning ================ ======================================= LUT_HASTL1 Do reverse linear interpolation on prelinearization table before calling the callback. LUT_HASTL2 Do reverse linear interpolation on postlinearization table after calling the callback. Flags are intended as an aid for building non-uniformly spaced CLUTs. Using flags results in "undoing" any linearization tables could apply. In such way, the programmer is expected to have in In[] always the original colorspace, and must return Out[] values always in original (non-postlinearized) space as well. The callback must return 0 if all is ok, or any other value to indicate error. If error condition is raised, whole CLUT construction is aborted. Parameters: Lut: a pointer to LUT structure Sampler: The callback function Cargo: A 32-bit value. Could be used as pointer to pass parameters to callback. dwFlags: any combination of LUT_HASTL1 or LUT_HASTL2 joined by bitwise-or operator '|' _________________________________________________________________________________ 12 - Named color functions _________________________________________________________________________________ Named color profiles are a special kind of profiles handling lists of spot colors. The typical example is PANTONE. CMM deals with named color profiles like all other types, except they must be in input stage and the encoding supported is limited to a one single channel of 16-bit indexes. Let's assume we have a Named color profile holding only 4 colors: · CYAN · MAGENTA · YELLOW · BLACK We create a transform using: hTransform = cmsCreateColorTransform(hNamedColorProfile, TYPE_NAMED_COLOR_INDEX, hOutputProfile, TYPE_BGR_8, INTENT_PERCEPTUAL, 0); "TYPE_NAMED_COLOR_INDEX" is a special encoding for these profiles, it represents a single channel holding the spot color index. In our case value 0 will be "CYAN", value 1 "MAGENTA" and so one. For converting between string and index there is an auxiliary function: int cmsNamedColorIndex(cmsHTRANSFORM hTransform, const char* ColorName); That will perform a look up on the spot colors database and return the color number or -1 if the color was not found. Other additional functions for named color transforms are: int cmsNamedColorCount(cmsHTRANSFORM hTransform); That returns the number of colors present on transform database. int cmsNamedColorInfo(cmsHTRANSFORM hTransform, int nColor, LPNAMEDCOLORINFO Info); That returns extended information about a given color. Named color profiles can also be grouped by using multiprofile transforms. In such case, the database will be formed by the union of all colors in all named color profiles present in transform. Named color profiles does hold two coordinates for each color, let's take our PANTONE example. This profile would contain for each color the CMYK colorants plus its PCS coordinates, usually in Lab space. lcms can work with named color using both coordinates. Creating a transform with two profiles, if the input one is a named color, then you obtain the translated color using PCS. Example, named color -> sRGB will give the color patches in sRGB In the other hand, setting second profile to NULL, returns the device coordinates, that is, CMYK colorants in our PANTONE sample. Example: Named color -> NULL will give the CMYK amount for each spot color. The transform must use TYPE_NAMED_COLOR_INDEX on input. That is, a single channel containing the 0-based color index. Then you have: cmsNamedColorIndex(cmsHTRANSFORM xform, const char* Name) for obtaining index from color name, and cmsNamedColorInfo(), cmsNamedColorCount() to retrieve the list. The profile is supposed to be for a unique device. Then the CMYK values does represent the amount of inks THIS PRINTER needs to render the spot color. The profile also has the Lab values corresponding to the color. This really would have no sense if gamut of printer were infinite, but since printers does have a limited gamut a PANTONE-certified printer renders colors near gamut boundaries with some limitations. The named color profile is somehow explaining which are these limitation for that printer. So, you can use a named color profile in two different ways, as output, giving the index and getting the CMYK values or as input and getting the Lab for that color. A transform named color -> NULL will give the CMYK values for the spot color on the printer the profile is describing. This would be the normal usage. A transform Named color -> another printer will give on the output printer the spot colors as if they were printed in the printer named color profile is describing. This is useful for soft proofing. As an additional feature, lcms can "group" several named color profiles into a single database by means of cmsCreateMultiprofileTransform(). Such case works as described above, but joining all named colors as they were in a single profile. _________________________________________________________________________________ 13. PostScript generation _________________________________________________________________________________ 3 functions carry the task of obtaining CRD and CSA. DWORD cmsGetPostScriptCSA(cmsHPROFILE hProfile, int Intent, LPVOID Buffer, DWORD dwBufferLen); DWORD cmsGetPostScriptCRD(cmsHPROFILE hProfile, int Intent, LPVOID Buffer, DWORD dwBufferLen); DWORD cmsGetPostScriptCRDEx(cmsHPROFILE hProfile, int Intent, DWORD dwFlags, LPVOID Buffer, DWORD dwBufferLen); cmsGetPostScriptCRDEx allows black point compensation using cmsFLAGS_BLACKPOINTCOMPENSATION in flags field. PostScrip colorflow is often done in a different way. Insted of creating a transform, it is sometimes desirable to delegate the color management to PostScript interpreter. These functions does translate input and output profiles into Color Space Arrays (CSA) and Color Rendering Dictionaries (CRD) · CRD are equivalent to output (printer) profiles. Can be loaded into printer at startup and can be stored as resources. · CSA are equivalent to input and workspace profiles, and are intended to be included in the document definition. These functions does generate the PostScript equivalents. Since the lenght of the resultant PostScript code is unknown in advance, you can call the functions with len=0 and Buffer=NULL to get the lenght. After that, you need to allocate enough memory to contain the whole block Example: Size = cmsGetPostScriptCSA(hProfile, INTENT_PERCEPTUAL, NULL, 0); If (Size == 0) error() Block = malloc(Size); cmsGetPostScriptCSA(hProfile, INTENT_PERCEPTUAL, Block, Size); Devicelink profiles are supported, as long as input colorspace matches Lab/XYZ for CSA or output colorspace matches Lab/XYZ for CRD. This can be used in conjuntion with cmsCreateMultiprofileTransform(), and cmsTransform2DeviceLink() to embed complex color flow into PostScript. WARNING: Preccision of PostScript is limited to 8 bits per sample. If you can choose between normal transforms and CSA/CRD, normal transforms will give more accurancy. However, there are situations where there is no chance. _________________________________________________________________________________ 14 - CGATS.13 - 200 _________________________________________________________________________________ This standard defines an exchange format for spectral measurement data, colorimetric data, and densitometric data in electronic form using keywords and data tables. It maintains human readability of the data as well as enabling machine readability. It includes a series of predefined keywords and data format identifiers and makes provision for the dynamic definition of additional keywords and data format identifiers as necessary. It was prepared by CGATS/SC3 in an effort to consolidate the common format requirements for the exchange of spectral measurement data, colorimetric data, and densitometric data in electronic form. These requirements presently appear in a number of CGATS and IT8 standards such as CGAT S.5, IT8.7/1, IT8.7/2, and IT8.7/3. While it is the intent that each of these individual standards will continue to identify required data, the basic data format and keywords and data identifier s will be defined in this standard for consistent use across all applicable standards. The Committee for Graphic Arts Technologies Standards (CGATS) was accredited by the American National Standards Institute in 1989 to serve as the coordinator of graphic arts standards activities. CGATS recommends the adoption and use of this standard by the graphic arts industry and its suppliers at their earliest convenience. lcms parser has following additions: .INCLUDE directive ------------------ Works like #include in C language. LABEL special keyword --------------------- _________________________________________________________________________________ LCMSHANDLE cmsIT8Alloc(void); _________________________________________________________________________________ Does allocate an empty CGATS.13/IT8 object. Mostly used for creating new IT8 files Returns: A handle to a CGATS.13, or NULL if error. _________________________________________________________________________________ void cmsIT8Free(LCMSHANDLE hIT8); _________________________________________________________________________________ Free any used memory. After this call the IT8 parser is not longer valid Parameters: hIT8: The CGATS.13 parser handle _________________________________________________________________________________ Tables _________________________________________________________________________________ In the lcms implementation, a CGATS.13/IT8 object may contain any number of tables. Tables are separated by END_DATA keyword. _________________________________________________________________________________ int cmsIT8TableCount(LCMSHANDLE hIT8); _________________________________________________________________________________ Returns the number of tables the CGATS.13/IT8 object contains. Parameters: hIT8: The CGATS.13 parser handle _________________________________________________________________________________ int cmsIT8SetTable(LCMSHANDLE hIT8, int nTable); _________________________________________________________________________________ Sets the current table on a given CGATS.13/IT8 object Parameters: hIT8: The CGATS.13 parser handle nTable: The table number (0 based) Returns: the number of tables the CGATS.13/IT8 object contains. Comments: Setting nTable to TableCount + 1 does allocate a new empty table _________________________________________________________________________________ Persistence _________________________________________________________________________________ These are functions to load/save CGATS.13/IT8 objects from file and memory stream. _________________________________________________________________________________ LCMSHANDLE cmsIT8LoadFromFile(const char* cFileName); _________________________________________________________________________________ Does allocate an CGATS.13/IT8 object and fills it with the contents of cFileName. Mostly used for reading existing IT8 files. Parameters: cFileName: The IT8/CGATS.13 file name to read/parse Returns: A handle to a CGATS.13, or NULL if error. _________________________________________________________________________________ LCMSHANDLE cmsIT8LoadFromMem(void *Ptr, size_t len); _________________________________________________________________________________ Same as anterior, but the IT8/CGATS.13 stream is readed from a memory block. Parameters: Ptr: Points to a block of contiguous memory containing the IT8/CGATS.13 stream. len: IT8/CGATS.13 stream s size measured in bytes. Returns: NULL on error, a profile handle on success. _________________________________________________________________________________ LCMSBOOL cmsIT8SaveToFile(LCMSHANDLE hIT8, const char* cFileName); _________________________________________________________________________________ Saves a IT8/CGATS.13 object to a file. Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SaveToMem(LCMSHANDLE hIT8, void *MemPtr, size_t* BytesNeeded); _________________________________________________________________________________ Saves a IT8/CGATS.13 object to a memory stream. Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ Type and comments _________________________________________________________________________________ The sheet type is a identifier placed on the very first line of the IT8/CGATS.13 stream. It can be IT8.7/xx or whatever. _________________________________________________________________________________ const char* cmsIT8GetSheetType(LCMSHANDLE hIT8); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SetSheetType(LCMSHANDLE hIT8, const char* Type); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SetComment(LCMSHANDLE hIT8, const char* cComment); _________________________________________________________________________________ This function is intended to provide a way automated IT8 creators can embed comments into file. Comments have no effect, and its only purpose is to document any of the file meaning. Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ Properties _________________________________________________________________________________ Properties are pairs <identifier> <value>. Each table may contain any number of properties. Its primary purpose is store simpler settings. _________________________________________________________________________________ LCMSBOOL cmsIT8SetPropertyStr(LCMSHANDLE hIT8, const char* cProp, const char *Str); LCMSBOOL cmsIT8SetPropertyDbl(LCMSHANDLE hIT8, const char* cProp, double Val); LCMSBOOL cmsIT8SetPropertyHex(LCMSHANDLE hIT8, const char* cProp, int Val); LCMSBOOL cmsIT8SetPropertyUncooked(LCMSHANDLE hIT8, const char* Key, const char* Buffer); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ const char* cmsIT8GetProperty(LCMSHANDLE hIT8, const char* cProp); double cmsIT8GetPropertyDbl(LCMSHANDLE hIT8, const char* cProp); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ int cmsIT8EnumProperties(LCMSHANDLE IT8, char ***PropertyNames); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle PropertyNames: A pointer to a variable which would recive a pointer to an array of property name strings. Returns: _________________________________________________________________________________ Datasets _________________________________________________________________________________ _________________________________________________________________________________ const char* cmsIT8GetDataRowCol(LCMSHANDLE IT8, int row, int col); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ double cmsIT8GetDataRowColDbl(LCMSHANDLE IT8, int row, int col); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SetDataRowCol(LCMSHANDLE hIT8, int row, int col, const char* Val); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SetDataRowColDbl(LCMSHANDLE hIT8, int row, int col, double Val); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ const char* cmsIT8GetData(LCMSHANDLE IT8, const char* cPatch, const char* cSample); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ double cmsIT8GetDataDbl(LCMSHANDLE IT8, const char* cPatch, const char* cSample); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SetData(LCMSHANDLE IT8, const char* cPatch, const char* cSample, char *Val); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SetDataDbl(LCMSHANDLE hIT8, const char* cPatch, const char* cSample, double Val); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ LCMSBOOL cmsIT8SetDataFormat(LCMSHANDLE IT8, int n, const char *Sample); _________________________________________________________________________________ Parameters: hIT8: The CGATS.13 parser handle Returns: _________________________________________________________________________________ int cmsIT8EnumDataFormat(LCMSHANDLE IT8, char ***SampleNames); _________________________________________________________________________________ Returns an array with pointers to the column names of currect table. Parameters: hIT8: The CGATS.13 parser handle SampleNames: A pointer to a variable of type char** which will hold the table. Returns: The number of column names in table. _________________________________________________________________________________ const char* cmsIT8GetPatchName(LCMSHANDLE hIT8, int nPatch, char* buffer); _________________________________________________________________________________ Fills buffer with the contents of SAMPLE_ID column for the set given in nPatch. That usually corresponds to patch name. Parameters: hIT8: The CGATS.13 parser handle nPatch : patch number to retreive name buffer: A memory buffer to recivepatch name, or NULL to allow function to allocate it own buffer. Returns: A pointer to the patch name, either the user-supplied buffer or an internal memory block.