1 //---------------------------------------------------------------------------------
3 // Little Color Management System
4 // Copyright (c) 1998-2011 Marti Maria Saguer
6 // Permission is hereby granted, free of charge, to any person obtaining
7 // a copy of this software and associated documentation files (the "Software"),
8 // to deal in the Software without restriction, including without limitation
9 // the rights to use, copy, modify, merge, publish, distribute, sublicense,
10 // and/or sell copies of the Software, and to permit persons to whom the Software
11 // is furnished to do so, subject to the following conditions:
13 // The above copyright notice and this permission notice shall be included in
14 // all copies or substantial portions of the Software.
16 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
18 // THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
19 // NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
20 // LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
21 // OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
22 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24 //---------------------------------------------------------------------------------
26 // This is the plug-in header file. Normal LittleCMS clients should not use it.
27 // It is provided for plug-in writters that may want to access the support
28 // functions to do low level operations. All plug-in related structures
29 // are defined here. Including this file forces to include the standard API too.
31 #ifndef _lcms_plugin_H
33 // Deal with Microsoft's attempt at deprecating C standard runtime functions
35 # if (_MSC_VER >= 1400)
36 # ifndef _CRT_SECURE_NO_DEPRECATE
37 # define _CRT_SECURE_NO_DEPRECATE
39 # ifndef _CRT_SECURE_NO_WARNINGS
40 # define _CRT_SECURE_NO_WARNINGS
49 // We need some standard C functions.
57 #ifndef CMS_USE_CPP_API
63 // Vector & Matrix operations -----------------------------------------------------------------------
65 // Axis of the matrix/array. No specific meaning at all.
72 cmsFloat64Number n[3];
82 CMSAPI void CMSEXPORT _cmsVEC3init(cmsVEC3* r, cmsFloat64Number x, cmsFloat64Number y, cmsFloat64Number z);
83 CMSAPI void CMSEXPORT _cmsVEC3minus(cmsVEC3* r, const cmsVEC3* a, const cmsVEC3* b);
84 CMSAPI void CMSEXPORT _cmsVEC3cross(cmsVEC3* r, const cmsVEC3* u, const cmsVEC3* v);
85 CMSAPI cmsFloat64Number CMSEXPORT _cmsVEC3dot(const cmsVEC3* u, const cmsVEC3* v);
86 CMSAPI cmsFloat64Number CMSEXPORT _cmsVEC3length(const cmsVEC3* a);
87 CMSAPI cmsFloat64Number CMSEXPORT _cmsVEC3distance(const cmsVEC3* a, const cmsVEC3* b);
89 CMSAPI void CMSEXPORT _cmsMAT3identity(cmsMAT3* a);
90 CMSAPI cmsBool CMSEXPORT _cmsMAT3isIdentity(const cmsMAT3* a);
91 CMSAPI void CMSEXPORT _cmsMAT3per(cmsMAT3* r, const cmsMAT3* a, const cmsMAT3* b);
92 CMSAPI cmsBool CMSEXPORT _cmsMAT3inverse(const cmsMAT3* a, cmsMAT3* b);
93 CMSAPI cmsBool CMSEXPORT _cmsMAT3solve(cmsVEC3* x, cmsMAT3* a, cmsVEC3* b);
94 CMSAPI void CMSEXPORT _cmsMAT3eval(cmsVEC3* r, const cmsMAT3* a, const cmsVEC3* v);
97 // Error logging -------------------------------------------------------------------------------------
99 CMSAPI void CMSEXPORT cmsSignalError(cmsContext ContextID, cmsUInt32Number ErrorCode, const char *ErrorText, ...);
101 // Memory management ----------------------------------------------------------------------------------
103 CMSAPI void* CMSEXPORT _cmsMalloc(cmsContext ContextID, cmsUInt32Number size);
104 CMSAPI void* CMSEXPORT _cmsMallocZero(cmsContext ContextID, cmsUInt32Number size);
105 CMSAPI void* CMSEXPORT _cmsCalloc(cmsContext ContextID, cmsUInt32Number num, cmsUInt32Number size);
106 CMSAPI void* CMSEXPORT _cmsRealloc(cmsContext ContextID, void* Ptr, cmsUInt32Number NewSize);
107 CMSAPI void CMSEXPORT _cmsFree(cmsContext ContextID, void* Ptr);
108 CMSAPI void* CMSEXPORT _cmsDupMem(cmsContext ContextID, const void* Org, cmsUInt32Number size);
110 // I/O handler ----------------------------------------------------------------------------------
112 struct _cms_io_handler {
114 void* stream; // Associated stream, which is implemented differently depending on media.
116 cmsContext ContextID;
117 cmsUInt32Number UsedSpace;
118 cmsUInt32Number ReportedSize;
119 char PhysicalFile[cmsMAX_PATH];
121 cmsUInt32Number (* Read)(struct _cms_io_handler* iohandler, void *Buffer,
122 cmsUInt32Number size,
123 cmsUInt32Number count);
124 cmsBool (* Seek)(struct _cms_io_handler* iohandler, cmsUInt32Number offset);
125 cmsBool (* Close)(struct _cms_io_handler* iohandler);
126 cmsUInt32Number (* Tell)(struct _cms_io_handler* iohandler);
127 cmsBool (* Write)(struct _cms_io_handler* iohandler, cmsUInt32Number size,
131 // Endianess adjust functions
132 CMSAPI cmsUInt16Number CMSEXPORT _cmsAdjustEndianess16(cmsUInt16Number Word);
133 CMSAPI cmsUInt32Number CMSEXPORT _cmsAdjustEndianess32(cmsUInt32Number Value);
134 CMSAPI void CMSEXPORT _cmsAdjustEndianess64(cmsUInt64Number* Result, cmsUInt64Number QWord);
136 // Helper IO functions
137 CMSAPI cmsBool CMSEXPORT _cmsReadUInt8Number(cmsIOHANDLER* io, cmsUInt8Number* n);
138 CMSAPI cmsBool CMSEXPORT _cmsReadUInt16Number(cmsIOHANDLER* io, cmsUInt16Number* n);
139 CMSAPI cmsBool CMSEXPORT _cmsReadUInt32Number(cmsIOHANDLER* io, cmsUInt32Number* n);
140 CMSAPI cmsBool CMSEXPORT _cmsReadFloat32Number(cmsIOHANDLER* io, cmsFloat32Number* n);
141 CMSAPI cmsBool CMSEXPORT _cmsReadUInt64Number(cmsIOHANDLER* io, cmsUInt64Number* n);
142 CMSAPI cmsBool CMSEXPORT _cmsRead15Fixed16Number(cmsIOHANDLER* io, cmsFloat64Number* n);
143 CMSAPI cmsBool CMSEXPORT _cmsReadXYZNumber(cmsIOHANDLER* io, cmsCIEXYZ* XYZ);
144 CMSAPI cmsBool CMSEXPORT _cmsReadUInt16Array(cmsIOHANDLER* io, cmsUInt32Number n, cmsUInt16Number* Array);
146 CMSAPI cmsBool CMSEXPORT _cmsWriteUInt8Number(cmsIOHANDLER* io, cmsUInt8Number n);
147 CMSAPI cmsBool CMSEXPORT _cmsWriteUInt16Number(cmsIOHANDLER* io, cmsUInt16Number n);
148 CMSAPI cmsBool CMSEXPORT _cmsWriteUInt32Number(cmsIOHANDLER* io, cmsUInt32Number n);
149 CMSAPI cmsBool CMSEXPORT _cmsWriteFloat32Number(cmsIOHANDLER* io, cmsFloat32Number n);
150 CMSAPI cmsBool CMSEXPORT _cmsWriteUInt64Number(cmsIOHANDLER* io, cmsUInt64Number n);
151 CMSAPI cmsBool CMSEXPORT _cmsWrite15Fixed16Number(cmsIOHANDLER* io, cmsFloat64Number n);
152 CMSAPI cmsBool CMSEXPORT _cmsWriteXYZNumber(cmsIOHANDLER* io, const cmsCIEXYZ* XYZ);
153 CMSAPI cmsBool CMSEXPORT _cmsWriteUInt16Array(cmsIOHANDLER* io, cmsUInt32Number n, const cmsUInt16Number* Array);
157 cmsTagTypeSignature sig;
158 cmsInt8Number reserved[4];
162 // Type base helper functions
163 CMSAPI cmsTagTypeSignature CMSEXPORT _cmsReadTypeBase(cmsIOHANDLER* io);
164 CMSAPI cmsBool CMSEXPORT _cmsWriteTypeBase(cmsIOHANDLER* io, cmsTagTypeSignature sig);
166 // Alignment functions
167 CMSAPI cmsBool CMSEXPORT _cmsReadAlignment(cmsIOHANDLER* io);
168 CMSAPI cmsBool CMSEXPORT _cmsWriteAlignment(cmsIOHANDLER* io);
170 // To deal with text streams. 2K at most
171 CMSAPI cmsBool CMSEXPORT _cmsIOPrintf(cmsIOHANDLER* io, const char* frm, ...);
173 // Fixed point helper functions
174 CMSAPI cmsFloat64Number CMSEXPORT _cms8Fixed8toDouble(cmsUInt16Number fixed8);
175 CMSAPI cmsUInt16Number CMSEXPORT _cmsDoubleTo8Fixed8(cmsFloat64Number val);
177 CMSAPI cmsFloat64Number CMSEXPORT _cms15Fixed16toDouble(cmsS15Fixed16Number fix32);
178 CMSAPI cmsS15Fixed16Number CMSEXPORT _cmsDoubleTo15Fixed16(cmsFloat64Number v);
180 // Date/time helper functions
181 CMSAPI void CMSEXPORT _cmsEncodeDateTimeNumber(cmsDateTimeNumber *Dest, const struct tm *Source);
182 CMSAPI void CMSEXPORT _cmsDecodeDateTimeNumber(const cmsDateTimeNumber *Source, struct tm *Dest);
185 //----------------------------------------------------------------------------------------------------------
187 // Plug-in foundation
188 #define cmsPluginMagicNumber 0x61637070 // 'acpp'
190 #define cmsPluginMemHandlerSig 0x6D656D48 // 'memH'
191 #define cmsPluginInterpolationSig 0x696E7048 // 'inpH'
192 #define cmsPluginParametricCurveSig 0x70617248 // 'parH'
193 #define cmsPluginFormattersSig 0x66726D48 // 'frmH
194 #define cmsPluginTagTypeSig 0x74797048 // 'typH'
195 #define cmsPluginTagSig 0x74616748 // 'tagH'
196 #define cmsPluginRenderingIntentSig 0x696E7448 // 'intH'
197 #define cmsPluginMultiProcessElementSig 0x6D706548 // 'mpeH'
198 #define cmsPluginOptimizationSig 0x6F707448 // 'optH'
200 typedef struct _cmsPluginBaseStruct {
202 cmsUInt32Number Magic; // 'acpp' signature
203 cmsUInt32Number ExpectedVersion; // Expected version of LittleCMS
204 cmsUInt32Number Type; // Type of plug-in
205 struct _cmsPluginBaseStruct* Next; // For multiple plugin definition. NULL for end of list.
209 // Maximum number of types in a plugin array
210 #define MAX_TYPES_IN_LCMS_PLUGIN 20
212 //----------------------------------------------------------------------------------------------------------
214 // Memory handler. Each new plug-in type replaces current behaviour
220 void * (* MallocPtr)(cmsContext ContextID, cmsUInt32Number size);
221 void (* FreePtr)(cmsContext ContextID, void *Ptr);
222 void * (* ReallocPtr)(cmsContext ContextID, void* Ptr, cmsUInt32Number NewSize);
225 void * (* MallocZeroPtr)(cmsContext ContextID, cmsUInt32Number size);
226 void * (* CallocPtr)(cmsContext ContextID, cmsUInt32Number num, cmsUInt32Number size);
227 void * (* DupPtr)(cmsContext ContextID, const void* Org, cmsUInt32Number size);
229 } cmsPluginMemHandler;
232 // ------------------------------------------------------------------------------------------------------------------
234 // Interpolation. 16 bits and floating point versions.
235 struct _cms_interp_struc;
237 // Interpolation callbacks
239 // 16 bits forward interpolation. This function performs precision-limited linear interpolation
240 // and is supposed to be quite fast. Implementation may be tetrahedral or trilinear, and plug-ins may
241 // choose to implement any other interpolation algorithm.
242 typedef void (* _cmsInterpFn16)(register const cmsUInt16Number Input[],
243 register cmsUInt16Number Output[],
244 register const struct _cms_interp_struc* p);
246 // Floating point forward interpolation. Full precision interpolation using floats. This is not a
247 // time critical function. Implementation may be tetrahedral or trilinear, and plug-ins may
248 // choose to implement any other interpolation algorithm.
249 typedef void (* _cmsInterpFnFloat)(cmsFloat32Number const Input[],
250 cmsFloat32Number Output[],
251 const struct _cms_interp_struc* p);
255 // This type holds a pointer to an interpolator that can be either 16 bits or float
257 _cmsInterpFn16 Lerp16; // Forward interpolation in 16 bits
258 _cmsInterpFnFloat LerpFloat; // Forward interpolation in floating point
261 // Flags for interpolator selection
262 #define CMS_LERP_FLAGS_16BITS 0x0000 // The default
263 #define CMS_LERP_FLAGS_FLOAT 0x0001 // Requires different implementation
264 #define CMS_LERP_FLAGS_TRILINEAR 0x0100 // Hint only
267 #define MAX_INPUT_DIMENSIONS 8
269 typedef struct _cms_interp_struc { // Used on all interpolations. Supplied by lcms2 when calling the interpolation function
271 cmsContext ContextID; // The calling thread
273 cmsUInt32Number dwFlags; // Keep original flags
274 cmsUInt32Number nInputs; // != 1 only in 3D interpolation
275 cmsUInt32Number nOutputs; // != 1 only in 3D interpolation
277 cmsUInt32Number nSamples[MAX_INPUT_DIMENSIONS]; // Valid on all kinds of tables
278 cmsUInt32Number Domain[MAX_INPUT_DIMENSIONS]; // Domain = nSamples - 1
280 cmsUInt32Number opta[MAX_INPUT_DIMENSIONS]; // Optimization for 3D CLUT. This is the number of nodes premultiplied for each
281 // dimension. For example, in 7 nodes, 7, 7^2 , 7^3, 7^4, etc. On non-regular
282 // Samplings may vary according of the number of nodes for each dimension.
284 const void *Table; // Points to the actual interpolation table
285 cmsInterpFunction Interpolation; // Points to the function to do the interpolation
289 // Interpolators factory
290 typedef cmsInterpFunction (* cmsInterpFnFactory)(cmsUInt32Number nInputChannels, cmsUInt32Number nOutputChannels, cmsUInt32Number dwFlags);
296 // Points to a user-supplied function which implements the factory
297 cmsInterpFnFactory InterpolatorsFactory;
299 } cmsPluginInterpolation;
301 //----------------------------------------------------------------------------------------------------------
303 // Parametric curves. A negative type means same function but analytically inverted. Max. number of params is 10
305 // Evaluator callback for user-suplied parametric curves. May implement more than one type
306 typedef cmsFloat64Number (* cmsParametricCurveEvaluator)(cmsInt32Number Type, const cmsFloat64Number Params[10], cmsFloat64Number R);
308 // Plug-in may implement an arbitrary number of parametric curves
312 cmsUInt32Number nFunctions; // Number of supported functions
313 cmsUInt32Number FunctionTypes[MAX_TYPES_IN_LCMS_PLUGIN]; // The identification types
314 cmsUInt32Number ParameterCount[MAX_TYPES_IN_LCMS_PLUGIN]; // Number of parameters for each function
316 cmsParametricCurveEvaluator Evaluator; // The evaluator
318 } cmsPluginParametricCurves;
319 //----------------------------------------------------------------------------------------------------------
321 // Formatters. This plug-in adds new handlers, replacing them if they already exist. Formatters dealing with
322 // cmsFloat32Number (bps = 4) or double (bps = 0) types are requested via FormatterFloat callback. Others come across
323 // Formatter16 callback
325 struct _cmstransform_struct;
327 typedef cmsUInt8Number* (* cmsFormatter16)(register struct _cmstransform_struct* CMMcargo,
328 register cmsUInt16Number Values[],
329 register cmsUInt8Number* Buffer,
330 register cmsUInt32Number Stride);
332 typedef cmsUInt8Number* (* cmsFormatterFloat)(struct _cmstransform_struct* CMMcargo,
333 cmsFloat32Number Values[],
334 cmsUInt8Number* Buffer,
335 cmsUInt32Number Stride);
337 // This type holds a pointer to a formatter that can be either 16 bits or cmsFloat32Number
339 cmsFormatter16 Fmt16;
340 cmsFormatterFloat FmtFloat;
344 #define CMS_PACK_FLAGS_16BITS 0x0000
345 #define CMS_PACK_FLAGS_FLOAT 0x0001
347 typedef enum { cmsFormatterInput=0, cmsFormatterOutput=1 } cmsFormatterDirection;
349 typedef cmsFormatter (* cmsFormatterFactory)(cmsUInt32Number Type, // Specific type, i.e. TYPE_RGB_8
350 cmsFormatterDirection Dir,
351 cmsUInt32Number dwFlags); // precision
353 // Plug-in may implement an arbitrary number of formatters
356 cmsFormatterFactory FormattersFactory;
358 } cmsPluginFormatters;
360 //----------------------------------------------------------------------------------------------------------
362 // Tag type handler. Each type is free to return anything it wants, and it is up to the caller to
363 // know in advance what is the type contained in the tag.
364 typedef struct _cms_typehandler_struct {
366 cmsTagTypeSignature Signature; // The signature of the type
368 // Allocates and reads items
369 void * (* ReadPtr)(struct _cms_typehandler_struct* self,
371 cmsUInt32Number* nItems,
372 cmsUInt32Number SizeOfTag);
375 cmsBool (* WritePtr)(struct _cms_typehandler_struct* self,
378 cmsUInt32Number nItems);
380 // Duplicate an item or array of items
381 void* (* DupPtr)(struct _cms_typehandler_struct* self,
385 // Free all resources
386 void (* FreePtr)(struct _cms_typehandler_struct* self,
389 // Additional parameters used by the calling thread
390 cmsContext ContextID;
391 cmsUInt32Number ICCVersion;
395 // Each plug-in implements a single type
398 cmsTagTypeHandler Handler;
402 //----------------------------------------------------------------------------------------------------------
404 // This is the tag plugin, which identifies tags. For writing, a pointer to function is provided.
405 // This function should return the desired type for this tag, given the version of profile
406 // and the data being serialized.
409 cmsUInt32Number ElemCount; // If this tag needs an array, how many elements should keep
412 cmsUInt32Number nSupportedTypes; // In how many types this tag can come (MAX_TYPES_IN_LCMS_PLUGIN maximum)
413 cmsTagTypeSignature SupportedTypes[MAX_TYPES_IN_LCMS_PLUGIN];
416 cmsTagTypeSignature (* DecideType)(cmsFloat64Number ICCVersion, const void *Data);
420 // Plug-in implements a single tag
424 cmsTagSignature Signature;
425 cmsTagDescriptor Descriptor;
429 //----------------------------------------------------------------------------------------------------------
431 // Custom intents. This function should join all profiles specified in the array in
432 // a single LUT. Any custom intent in the chain redirects to custom function. If more than
433 // one custom intent is found, the one located first is invoked. Usually users should use only one
434 // custom intent, so mixing custom intents in same multiprofile transform is not supported.
436 typedef cmsPipeline* (* cmsIntentFn)( cmsContext ContextID,
437 cmsUInt32Number nProfiles,
438 cmsUInt32Number Intents[],
439 cmsHPROFILE hProfiles[],
441 cmsFloat64Number AdaptationStates[],
442 cmsUInt32Number dwFlags);
445 // Each plug-in defines a single intent number.
448 cmsUInt32Number Intent;
450 char Description[256];
452 } cmsPluginRenderingIntent;
455 // The default ICC intents (perceptual, saturation, rel.col and abs.col)
456 CMSAPI cmsPipeline* CMSEXPORT _cmsDefaultICCintents(cmsContext ContextID,
457 cmsUInt32Number nProfiles,
458 cmsUInt32Number Intents[],
459 cmsHPROFILE hProfiles[],
461 cmsFloat64Number AdaptationStates[],
462 cmsUInt32Number dwFlags);
465 //----------------------------------------------------------------------------------------------------------
467 // Pipelines, Multi Process Elements.
469 typedef void (* _cmsStageEvalFn) (const cmsFloat32Number In[], cmsFloat32Number Out[], const cmsStage* mpe);
470 typedef void*(* _cmsStageDupElemFn) (cmsStage* mpe);
471 typedef void (* _cmsStageFreeElemFn) (cmsStage* mpe);
474 // This function allocates a generic MPE
475 CMSAPI cmsStage* CMSEXPORT _cmsStageAllocPlaceholder(cmsContext ContextID,
476 cmsStageSignature Type,
477 cmsUInt32Number InputChannels,
478 cmsUInt32Number OutputChannels,
479 _cmsStageEvalFn EvalPtr, // Points to fn that evaluates the element (always in floating point)
480 _cmsStageDupElemFn DupElemPtr, // Points to a fn that duplicates the stage
481 _cmsStageFreeElemFn FreePtr, // Points to a fn that sets the element free
482 void* Data); // A generic pointer to whatever memory needed by the element
485 cmsTagTypeHandler Handler;
487 } cmsPluginMultiProcessElement;
489 //----------------------------------------------------------------------------------------------------------
490 // Optimization. Using this plug-in, additional optimization strategies may be implemented.
491 // The function should return TRUE if any optimization is done on the LUT, this terminates
492 // the optimization search. Or FALSE if it is unable to optimize and want to give a chance
493 // to the rest of optimizers.
495 typedef void (* _cmsOPTeval16Fn)(register const cmsUInt16Number In[],
496 register cmsUInt16Number Out[],
497 register const void* Data);
499 typedef void (* _cmsOPTfreeDataFn)(cmsContext ContextID, void* Data);
500 typedef void* (* _cmsOPTdupDataFn)(cmsContext ContextID, const void* Data);
503 typedef cmsBool (* _cmsOPToptimizeFn)(cmsPipeline** Lut,
504 cmsUInt32Number Intent,
505 cmsUInt32Number* InputFormat,
506 cmsUInt32Number* OutputFormat,
507 cmsUInt32Number* dwFlags);
509 // This function may be used to set the optional evaluator and a block of private data. If private data is being used, an optional
510 // duplicator and free functions should also be specified in order to duplicate the LUT construct. Use NULL to inhibit such functionality.
512 CMSAPI void CMSEXPORT _cmsPipelineSetOptimizationParameters(cmsPipeline* Lut,
513 _cmsOPTeval16Fn Eval16,
515 _cmsOPTfreeDataFn FreePrivateDataFn,
516 _cmsOPTdupDataFn DupPrivateDataFn);
521 // Optimize entry point
522 _cmsOPToptimizeFn OptimizePtr;
524 } cmsPluginOptimization;
526 //----------------------------------------------------------------------------------------------------------
528 #ifndef CMS_USE_CPP_API
534 #define _lcms_plugin_H