little cms Engine 1.17
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 �
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 �
Parameters:
TempK: Temperature in �
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.
|
