Magazyn Amiga 12

home *** CD-ROM | disk | FTP | other *** search

/ Magazyn Amiga 12 / MA_Cover_12.iso / devs / ics / software / ics.lzh / ICS / Programmer / ICS.doc < prev

Wrap

Text File | 1999-05-23 | 41.9 KB | 993 lines

ICS PROGRAMMER MANUAL TABLE OF CONTENTS ics.library/CreateIDC ics.library/CreateIDCA ics.library/CreateIDCTransform ics.library/CreateIDCTransformA ics.library/DeleteIDC ics.library/DeleteIDCTransform ics.library/ICSErr ics.library/ICSFault ics.library/ICSStatusWin ics.library/ICSStatusWinA ics.library/SetIDCMode ics.library/SetupIDCColorMatching ics.library/SetupIDCColorMatchingA ics.library/TranslateColors ics.library/--background-- ics.library/--background-- COPYRIGHT This file and all other parts of the ICS package are Copyright 1999 Wolf Faust. All rights reserved. You may not copy or distribute ICS without written permission by: Wolf-Jürgen Faust Am Dorfgarten 10 60435 Frankfurt Germany Tel: ++49-69-5486556 Fax: ++49-69-95409598 email: wfaust@compuserve.com PURPOSE The ics.library alias ICS ensures that a color image, graphic or text object can be scanned/rendered/printer as close as possible to its original intent on any device, despite differences in imaging technologies and color capabilities between devices. Whether you are scanning an image or other graphic on a color scanner, downloading it over the Internet, viewing or editing it on the screen, or outputting it to video, paper, film, or other media, ics.library helps you keep its colors consistent and accurate. Color Management Systems implemented like the ICS library are of great importance to current and future application software as need rises. Here some examples of the use of such a system: - Converting an image colors from known color spaces like PhotoCD, sRGB, Monitor, Scanner to the users Monitor. - Convert colors used by the user on his monitor to printer colors - Convert colors used by the user on his display to another persons display - Color correct video - Changes colors for different viewing conditions (white point, surrround light,...). - Convert colors between different device dependent and device independent color spaces: RGB<->CIE Lab<->CIE XYZ<->CMYK<->... But ICS also allows profiling devices. This means, it will provide methods for characterizing devices. Once measured, these devices become a reliable and predictable part of your system. Note that ICS is an ongoing project. The amount of devices supported is currently not complete. Please contact Wolf Faust for the latest info (address above). Currently planned development stages (development did start summer 1997): 1st Generation (release planned spring 1999): Scanner characterization. Scanner -> Monitor/Device color transformation. 2nd Generation ICC V3.4 standard profile support for exchanging profiles with Mac, PC, SGI,... Device (Monitor) -> Device (Monitor) color transformation Input/Device (Scanner/Monitor) -> Target (printer) color transformation Support color spectrometers (X-Rite's Monitor Optimizer) 3rd Generation Printer characterization. Support color spectrometers (X-Rite's Digital Swatchbook) 4th Generation: Provide a mechanism for external CMM's. This document describes the 1st generation of the ICS library. REQUIREMENTS - Well, first you must legaly own this software ;-) - This library does call dos functions. Thus all calls to this library must be done by a process!!! - Some memory and disk space... - Kickstart 2.04 or higher. OVERVIEW The basic procedure for using this library in order to convert a color from one device (scanner/monitor/printer) to another: 1. You should include following headers if not already present in your application source: #include <inttypes.h> #include <proto/ics.h> 2. In your application: First, create an interchange device context handle using CreateIDC(). 3. Next setup ICS preferences as wanted using SetupIDCColorMatching() and SetIDCMode(). Or offer a ICS Setup option/menu item for the user wich than calls SetupIDCColorMatching() on an existing IDC handle created with 2. 4. Create a color transformation function based on the preferences made in 3. using CreateIDCTransform(). 5. Convert your colors using TranslateColors(). 6. Free all resources using DeleteIDCTransform() and DeleteIDC() before closing the library. 7. If you want to support ICS in a scanner driver, there are some things you should know in order to increase the quality: - Warning: ICS might not work perfect with grayscale data as input as the calibration target was scanned using the scanners color and not grayscale mode. Even with the target scanned in grayscale mode, certain things can only be guessed wich is why you should do following: + Try avoid grayscale as input data for ICS. + If possible scan using the color mode and let ICS convert color to grayscales while performing the correction. This is the recommended default method. There is a benefit to it: the number of shades scanned is usualy increased by this method resulting in higher quality. + A rather bad method: Do not allow using ICS with grayscale as input. Well, I wouldn't recommend this as ICS hardly make things worse with grayscale as input. - It's recommended to provide a "Mode" cycle gadget in your scanner driver. The Mode gadget should provide a "Calibration" and a "ICS Correction" setting. When set to "Calibration", the scanner software should be setup to provide linear non-gamma corrected values. Often scanners do offer various settings for NTSC or Gamma correction. These settings may also be part of the Mode gadget, but often do not provide the best quality when calibrating ICS. The "Calibration" Mode should be used by the user to calibrate the scanner. So the software should only provide uncorrected linear data when calibrating and using ICS. - The "ICS Correction" should be the default mode and use the ICS library for correcting the scanned colors. The scanner must be setup in the exact same way as with the "Calibration" mode wich was used by the user to calibrate ICS. Your scanner driver should than ask ICS to correct the provided data. Note that ICS can provide download tables for your scanner in order to increase the precession. Or implement the "Calibration" and "ICS Correction" settings as mutual exclusive menu items. - Your scan software should provide an "ICS Setup" button in order to setup ICS. Your software should call SetupIDCColorMatching() when the user hits the button. ics.library/--version-- ics.library/--version-- NOTES This document describes ics.library V2.00 or higher. ics.library/CreateIDC ics.library/CreateIDC NAME CreateIDC -- create a new interchange device context handle (IDC) SYNOPSIS IDC = CreateIDCA(tags); D0 A0 void *CreateIDCA(struct TagItem *); IDC = CreateIDC(Tag1, ...) void *CreateIDC(ULONG, ...) FUNCTION This function creates a handle to an interchange device context object (IDC). The IDC object mainly contains all global settings and preferences used by the ics.library. The IDC settings in the IDC object mainly describe the devices (monitor, scanner,...) used by the user. It also contains the settings on how the transformation between device dependent color spaces should be done. The contents of IDC is hidden from the user and changes to the IDC object must be done using the offered ics.library function calls. Note that on creation of the IDC object, the ICS library does read the global systems ICS settings. So once you created an IDC, changes to the global ICS settings by a different application will have no effect on the functioning of previously generated IDC. Do not assume certain settings in a new IDC objects. Specificly, check if the color mapping is turned on using SetIDCMode() when you want to generate a real color mapping function using CreateIDCTransform(). Calls to CreateIDC must be matched by calls to DeleteIDC(). INPUTS tags - Following tags are supported (some are always required!). The tags are mainly added for safety so that ICS may workarround problems with faulty applications. ICS_APPNAME - The required value of this tag must be a string pointer not longer than 25 chars containing the name of your application. The name should follow the rules for AmigaDOS filenames (no ~?#... chars). The name given will be copied by ICS to an internal buffer and will be used for saving settings or displaying messages. ICS_APPNAMEVERSION - This required tag specifies a uint32_t value containg the version of your application. The version given may be used by future version of ICS in order to enable/disable new features for specific applications. ICS_APPICSVERSION - This required tag specifies the latest version of ICS library you developed your application for. The version given may allow ICS to identify the capabilities of your application so that new versions of the ICS library can behave in a compatible way if required. I hope the API of this library is well designed so that the library never makes use of this value. But again, safety first. So specify the library version (see ics.library/--version-- above) ICS_PREFSFILE - Use this tag to specify a string pointer containg the full path and name of an ICS preferences file. ICS preferences settings will be loaded from the specified file. However, if you do call SetupIDCColorMatching() and the users saves his settings, they will overwrite the normal ICS preferences settings. So this is just for loading custom preferences. You may specify NULL for the default preferences file. If the specified file does not exist or has the wrong version, ICS will silently skip the ICS_PREFSFILE tag and normal preferences will be used. RESULTS IDC - pointer to IDC object or NULL in case of failure. There is no error id or text available in case of a failure. However, the most likely reason for a failure is simple lack of memory. SEE ALSO DeleteIDC(). ics.library/CreateIDCTransform ics.library/CreateIDCTransform NAME CreateIDCTransform -- creates a transformation function handle. SYNOPSIS hColorTransform = CreateIDCTransformA(idc,tags); D0 A0 A1 HTRANSFORM CreateIDCTransformA(void *, struct TagItem *); hColorTransform = CreateIDCTransform(idc,Tag1, ...) HTRANSFORM CreateIDCTransform(void *, ULONG, ...) FUNCTION This function returns a handle to a transformation function (HTRANSFORM) used to convert colors between two devices specified by the IDC given. The transformation functions is basicly created from the settings of the IDC object. The necessary device profiles are read from disk and a transformation function is calculated. Depending on the library version and type of transformation, CreateIDCTransform might take much of your systems free RAM in order to create interpolation tables used to speed up the correction later on. Thus the amount of free memory can have a huge effect on the speed and precission of the created mapping function. NOTE: a call to CreateIDCTransform() can take several minutes. Thus it is a good idea to create a busy pointer for your windows. Also, try to avoid unnecessary calls to CreateIDCTransform(). For instance, if you want to convert many images using the same transformation function, only call CreateIDCTransform() once. Use ICS_StatusOpen tag in order to get a status window displayed allowing the user to abort CreateIDCTransform if wanted. You can call CreateIDCTransform() with the color mapping turned off (see SetIDCMode()). In this case, a transformation function is created leaving colors unchanged when mapping. You can not use this transformation function while ICS is enabled. ICS may be enabled/disabled by calls to SetIDCMode() or SetupIDCColorMatching(). If you want a valid and functional transformation function, query the mapping mode of the created IDC using SetIDCMode(). Than enable the mapping for calling CreateIDCTransform(). Afterwoods you set the ICS mode back to it's default. This way you can enabled and disable ICS as wanted and use existing transformations. It's a nice and quick method to disable the color mapping with SetIDCMode(idc, ICS_OFF) prior to CreateIDCTransform() in order to use the same program calls to the ICS library without doing any color mapping. However, in this case you have to delete the transformation function first before you can generate a real color mapping function based on the user selected device profiles. All successfull created transformation functions must be freed using DeleteIDCTransform(). CreateIDCTransform() does call ICSStatusWin() with the given tags. This means, you can automaticly get a status window with CreateIDCTransform() showing the user the progress of CreateIDCTransform() and allowing the user to abort the action. CreateIDCTransform() can also provide you with the data required to generate a download table for your scanner. INPUTS idc - pointer to an interchanged device context object created using CreateIDC(). It contains all the preferences and settings describing the wanted transformation function. tags - Following tags are supported: ICS_TransferDevices - descibes from source/destination device to be used. Set to: ICS_INPUT_DEVICE Specifies that you want to transform input device colors for the display device. Currently you MUST use this. ICS_ScanTLCGray - ICS_ScanTLCRed - ICS_ScanTLCGreen - ICS_ScanTLCBlue - Disables TLC/Graybalance correction and the library will return a (uint16_t *) to the 1D LUTs in the given address so that you can apply the TLC table (download to scanner) yourself. Some scanners allow drivers to download a correction table. Often this is combined with a greater precission as the internal processing is done with more bits than the data is sent to the computer (ie. 12 Bit scanners providing 8 Bit grayscale values,...). One of the first corrections done by the ICS library is graybalance and linearization of the input data based on the scanner profile given. This is done by using simple 1D LUTs. You can ask the ICS library using these tags for the 1D LUTs used in order to download them to the scanner. The scanner will than do the correction. Because of this, it is important: A. do not specify these tags unless you really apply the returned LUTs to the input data yourself. B. ICS will return NULL in the address given by the tag values if no LUT is available. In this case, the general rule applies: always use the same correction in your software as used during the calibration of the scanner using ICS. This correction should return linear data and not gamma corrected for best quality. C. You may only ask for ICS_ScanTLCGray or ICS_ScanTLCRed, ICS_ScanTLCGreen, ICS_ScanTLCBlue, or both. Just asking for ICS_ScanTLCRed is not supported. D. The provided table must not be altered. If your scanners wants 12Bit->8Bit tables, it's up to you to allocated and calculate the values from the table provided. E. The values in the table are unsigned 16 Bit values (0-65535). Black is 0 and White is 65535 for both, color and grayscale tables. F. These tags are only supported with ICS_TransferDevices set to ICS_INPUT_DEVICE. G. The pointer address given must be initialized with a NULL pointer. Check if the pointer is still NULL after the CreateIDCTransform() call in order to know if the library provided a table. H. It's your responsibility to not use the returned tables if ICS is switched off by you later on. Use SetIDCMode() to check if the ICS mode is off. So only use the tables if ICS is enabled during the TranslateColors() call. ICS_StatusOpen - This will open the status window as descibed by ICSStatusWin(). The status window will automaticly be closed on return of CreateIDCTransform() unless you use the ICS_StatusKeep tag. The status window will always automaticly be closed when calling DeleteIDCTransform() See ICSStatusWin() for more info. ICS_Screen - See ICSStatusWin() for more info. ICS_StatusClose - Do not use in CreateIDCTransform(). ICS_StatusCheck - Do not use in CreateIDCTransform(). ICS_StatusActivate - See ICSStatusWin(). ICS_StatusTitle - See ICSStatusWin(). ICS_StatusText - See ICSStatusWin(). ICS_StatusProgress - See ICSStatusWin(). ICS_StatusKeep - Set this bool tag value to TRUE if you want the status window to be left opened for further progress display. The status window can be further be controlled by ICSStatusWin(). ICS_StatusDisableAbort - Set the BOOL value of this tag to TRUE/FALSE in order to disable/enable the abort gadget of the status window (default: enabled). ICS_StatusAbortPtr - The value of this tag is a pointer to an uint32_t var. This var gets set to non-zero if user wants to abort. Note that the preferred way of checking for user aborts is using the ICS_StatusCheck tag. ICS_StatusAbortPtr should only be used when calls to ICSStatusWin() are impossible by the application. ICS_TextAttr - Font (struct TextAttr *) to be used for the window's gadgets and menus. If this tag is not provided or its value is NULL, the default font of the screen on which the requesting window opens will be used. This font must already be in memory as ICS calls OpenFont() and not OpenDiskFont(). The font must be monospaced. ICS will check for an allowed font in following order: 1. ICS_TextAttr tag 2. default font of Screen used for the window 3. system default font 4. Topaz80 RESULTS htransform - handle for a transformation function or NULL if failure. Use ICSFault() or ICSErr() for further error information. SEE ALSO DeleteIDCTransform(), ICSStatusWin(), SetIDCMode() ics.library/DeleteIDC ics.library/DeleteIDC NAME DeleteIDC -- delete an interchange device context object (IDC). SYNOPSIS DeleteIDC(idc); A0 VOID DeleteIDC(void *); FUNCTION Deletes an interchanged device context object (IDC). Note that all transformation functions created with the IDC object using CreateIDCTransform() must be freed using DeleteIDCTransform() before calling DeleteIDC(). Note that the handle 'idc' is invalid after this function is called. INPUTS idc - pointer to an interchanged device context object created using CreateIDC(). SEE ALSO CreateIDC() ics.library/DeleteIDCTransform ics.library/DeleteIDCTransform NAME DeleteIDCTransform -- delete a transformation function. SYNOPSIS DeleteIDCTransform(hColorTransform); A0 VOID DeleteIDC(void *); FUNCTION Deletes a device transformation function. INPUTS hColorTransform - pointer to transformation function created using CreateIDCTransform(). SEE ALSO CreateIDCTransform() ics.library/ICSErr ics.library/ICSErr NAME ICSErr -- Return extra error information from the library SYNOPSIS error = ICSErr(idc); D0 A0 uint_fast32_t ICSErr(void *); FUNCTION Most library routines return zero to indicate an error. When this happens (or whatever the defined error return for the routine) this routine may be called to determine more information. The error yelled by the library is always specific for the used IDC object. Note that every successfull new call to one of the ICS library functions will set the error to 0 for the given IDC. Use ICSFault() to get the text associated with the last error. RESULTS error - non zero if a fault appeared in the last ics library function call. Error values 1 - ICS_ERRMSGLIMIT should not cause an error message from your application as the ICS library already showed the error to the user. Just abort quietly in this case. INPUTS idc - the interchanged device context you want to check for errors. SEE ALSO ICSFault() ics.library/ICSFault ics.library/ICSFault NAME ICSFault -- Returns the text associated with the last error SYNOPSIS errtext = ICSFault(idc, header); D0 A0 A1 PSTR ICSFault(void *, PSTR); FUNCTION Most library routines return zero to indicate an error. When this happens (or whatever the defined error return for the routine) this routine may be called to determine more information. Unlike ICSErr(), this function returns a pointer to a formated textstring describing the problem in detail associated with the IDC used. The error text can be used to prompt a requester. The function returns NULL in case no error appeared since your last call to ICS library with the given IDC object. WARNING: the error text may be more than 80 chars in size. However, you must be sure it is formated in order to display nicely using EasyRequest(). The string pointer is only valid until you call another ICS library function. RESULTS errtext - pointer to locale string containg error text or zero no fault appeared in the last ICS library call function call. INPUTS idc - the interchanged device context you want to check for errors. header - text string used as header in the error message. SEE ALSO ICSErr() ics.library/ICSStatusWin ics.library/ICSStatusWin NAME ICSStatusWinA-- open/close and control a status/progess window SYNOPSIS ret = ICSStatusWinA(hColorTransform, tags) D0 A0 A1 uint_fast32_t = ICSStatusWinA((struct Transform *, struct TagItem *) ret = ICSStatusWin(hColorTransform, ...) uint_fast32_t = ICSStatusWin((struct Transform *, ...) FUNCTION This function can be used to open, close and control a status window for showing the user progress of the calculation. It also offers the user to abort processing. The window runs as seperate process in order to give quick response to the user. The status window is always linked to a transformation handle wich must be given as first function argument. You can open, close and set attributes of the status window as you like. So you may use it in your program for various other tasks. Note that you can also add the tags listed below during the CreateIDCTransform() call with ICS_StatusOpen defined. In this case a status window is opened automaticly for you during the CreateIDCTransform() call. The status window can be closed by using the ICS_StatusClose tag. The status window will also be automaticly closed by the DeleteIDCTransform(). All text arguments are copied to internal buffers and thus can be altered/deleted after the ICSStatusWin() call. INPUTS hColorTransform - pointer to transformation function created using CreateIDCTransform(). tags - Following tags are supported: ICS_StatusOpen - A progress/status window will be opened for the given transformation handle. The value of this tag must be a screen pointer or NULL. If NULL, the screen pointer provided ICS_Screen will be used. If ICS_Screen is NULL too, the default public screen will be used. ICS_Screen - Screen pointer on wich to open the Setup window if NULL was specified by the ICS_StatusOpen. ICS_Screen is an alternativ form to provide the screen pointer. ICS_Screen is a global tag supported by various ICS functions. It allows you to store all ICS tags in a single array in your application and only a single screen pointer value has to be changed if needed. ICS_StatusClose - This will close the status window. Set the tag value to 0. The status window will automaticly close when calling DeleteIDCTransform(). ICS_StatusActivate - Use this flag if you want the status window to automatically become the active window when opening the status window. Or you can use this flag to make the status window active after creation. The active window is the one that receives input from the keyboard and mouse. By default, the ICS status window is not active. It's not recommended to make the status window active in order to avoid disturbing the user working on a different screen/window. Please use this flag thoughtfully and carefully. ICS_StatusCheck - This function should be called from time to time in order to check if the user asked for aborting the task. The function returns non-zero once for each abort request by the user. You can use ICS_StatusDisableAbort in order to disable the user from aborting. In this case calls with ICS_StatusCheck are not necessary anymore. Set the value of this tag to 0! ICS_StatusTitle - The value of this tag must be a string pointer containing the new window title of the status window. The text specified by the given string pointer is copied to an internal buffer and thus can be altered by the application after the call. Providing NULL as string pointer will cause ICS to set the window title (wich is the default after creating the status window). Note that the status title is set by ICS usualy by all major calculations making the a title change worth it. ICS_StatusText - The value of this tag is a string pointer to the body text. The text is copied to an internal buffer and thus can be altered by the application after the call. Note that the status text is altered by ICS for major calculations in order to show the user the progress. You disable this default feature by defining a string with ICS_StatusText. ICS than assumes you want to control the text of the status window. Providing NULL as string pointer will cause ICS to set the status text by itself again (as said, this is the default after creating the status window). ICS_StatusProgress - This tag allows the status window to show a graphical bar for the progress done. The tag value given describes the percentage done (0-100). Any ICS_StatusText tag will reset the progress value automaticly to 0. ICS_StatusDisableAbort - Set the BOOL value of this tag to TRUE/FALSE in order to disable/enable the abort gadget of the status window (default: enabled). ICS_StatusAbortPtr - The value of this tag is a pointer to an uint32_t var. This var gets set to non-zero if user wants to abort. Note that the preferred way of checking for user aborts is using the ICS_StatusCheck tag. ICS_StatusAbortPtr should only be used when calls to ICSStatusWin() are impossible by the application. ICS_TextAttr - Font (struct TextAttr *) to be used for the window's gadgets and text. If this tag is not provided or its value is NULL, the default font of the screen on which the requesting window opens will be used. This font must already be in memory as ICS calls OpenFont() and not OpenDiskFont(). The font must be monospaced. ICS will check for an allowed font in following order: 1. ICS_TextAttr tag 2. default font of Screen used for the window 3. system default font 4. Topaz80 RESULTS Zero is returned in case of success. You can safely call this function with various tags even if no status window exists. The function will simply return zero in this case - just like a status window exists. So basicly only ICS_StatusOpen will return an error and needs special error checking. SEE ALSO CreateIDCTransform() ics.library/SetIDCMode ics.library/SetIDCMode NAME SetIDCMode -- Query, enable or disable color mapping SYNOPSIS oldmode = SetIDCMode(idc, newmode); D0 A0 D0 uint_fast32_t SetIDCMode(void *, uint_fast32_t); FUNCTION This function causes color mapping to be enabled, disabled, or queried on a given interchange device context (IDC). The newmode parameter can take one of the following constant values: ICS_ON : Turns color mapping on. ICS_OFF : Turns color mapping off. ICS_QUERY: Queries the current state of color mapping of the IDC. If ICS_QUERY is specified and the function succeeds, the nonzero value returned is ICS_ON or ICS_OFF to indicate the current mode. You can disable and enable the color mapping of a given IDC and it's associated transformation functions. But you must not enable the mapping mode using ICS_ON if a transformation function was created by CreateIDCTransform() with the IDC handle set to ICS_OFF. RESULTS oldmode - If the function succeeds, the return value is a nonzero value describing the previous mode: ICS_OFF or ICS_ON. 0 is returned in case of failure. Use ICSFault() or ICSErr() for further error information. INPUTS idc - pointer to the interchanged device context. newmode - one of the following flags: ICS_OFF, ICS_ON, ICS_QUERY. SEE ALSO CreateIDCTransform() ics.library/SetupIDCColorMatching ics.library/SetupIDCColorMatching NAME SetupIDCColorMatching -- Create a color mapping preferences window. SYNOPSIS ret = SetupIDCColorMatchingA(idc, screen, tags); D0 A0 A1 D0 uint32_t SetupIDCColorMatchingA(void *, struct Screen *, struct TagItem *); ret = SetupIDCColorMatching(idc, screen, Tag1, ...) uint32_t SetupIDCColorMatching(void *, struct Screen *, ULONG, ...) FUNCTION The SetupIDCColorMatching function creates a Color Management requester window that lets the user choose whether to enable color mapping, and if so, provides control over the color profiles used and the rendering intent. Important: note that the settings made by the user may only be valid for the idc handle used in the SetupIDCColorMatching() call. Thus you should create and keep an idc handle as long as possible. You should free any transformation function created with CreateIDCTransform() after calling SetupIDCColorMatching() if the user altered the settings (return value of 3). So it's a good idea to create a transformation function during the startup of your software once. Only free and afterwoods create the transformation function if the user altered the settings. This avoids calling the computing intensive CreateIDCTransform() function. Note that the user might disabled/enabled ICS when calling SetupIDCColorMatching(). So you should not call SetupIDCColorMatching() while a transformation function linked to the IDC is used simultaniously. Other changes than enabling/disabling ICS do not affect existing transformation functions. RESULTS ret - A return value: 0 - An error occured, the IDC is left unchanged. Use ICSFault() or ICSErr() for further error information. 1 - The user quit the setup window using the cancel gadget. 2 - The user quit the setup window using the Save or Use gadget. The user left the settings unchanged. 3 - The user quit the setup window using the Save or Use gadget. The user altered the ICS settings. Free any transfer function handle created by CreateIDCTransform() after this call. INPUTS idc - handle to the interchanged device context you want the user to alter. screen - Pointer to an intuition screen you want the requester to appear on. Do not close the screen by another task while requester is on the screen. Or NULL the ICS_Screen or default public screen should be used. The screen must be at least 640*200 pixels in size. tags - Following tags are supported: ICS_Screen - Screen pointer on wich to open the Setup window if NULL was specified by the screen argument. If neither, screen and ICS_Screen were defined, the default public screen will be used. ICS_TextAttr - Font (struct TextAttr *) to be used for the window's gadgets and menus. If this tag is not provided or its value is NULL, the default font of the screen on which the requesting window opens will be used. This font must already be in memory as ICS calls OpenFont() and not OpenDiskFont(). The font must be monospaced. ICS will check for an allowed font in following order: 1. ICS_TextAttr tag 2. default font of Screen used for the window 3. system default font 4. Topaz80 ics.library/TranslateColors ics.library/TranslateColors NAME TranslateColors -- Translate an array of colors. SYNOPSIS success = TranslateColors(hColorTransform, paInoutColors, nColors, ctInpout, paOutputColors, ctOutput); D0 A0 A1 D0 D1 A2 D2 BOOL TranslateColors(HTRANSFORM, PCOLOR, uintmax_t, COLORTYPE, PCOLOR, COLORTYPE); FUNCTION The TranslateColors function translates an array of colors from the source color space to the destination color space as defined by a color transform. If the input and the output color types are not compatible with the color transform or are unsupported, this function fails and ICSFault() can be used to get more info about the cause. If ICS is disabled because of preferences or because you used SetIDCMode(), this function will do no color correction and input colors are copied to the output colors by TranslateColors. It might also be usefull to convert colors between different color spaces using ICS (for instance CIE Lab -> CIE xyz,...). Note: Each element of the array pointed to by paInoutColors and paOutputColors is of the size specified by the ctInpout and ctOutput type. So when converting an COLOR_URGB array of 6 elements, the size of the array is assumed sizeof(struct URGBCOLOR)*6 and not sizeof(struct COLOR)*6. Note: paInoutColors and paOutputColors may point to the same color(s). Note: With COLOR_UGRAY black is 0 and white is 65535. Note: With COLOR_URGB black is 0/0/0 and white is 65535/65535/65535. Note: Avoid COLOR_UGRAY as input color space when possible (why? See "--background--" above!). The quality is limited and future version of ICS might not allow grayscale correction. Use COLOR_URGB as source if you want COLOR_UGRAY as output whenver possible. Note: Avoid calling TranslateColors() for a single pixel. Performance can be dramaticly lowered. When converting an image, try to provide at least a single image line. RESULTS success - returns TRUE if no error appeared. Otherwise FALSE. Use ICSFault() or ICSErr() for further error information. INPUTS hColorTransform - Identifies the color transform to use. Created by CreateIDCTransform(). paInputColors - Pointer to an array of nColors COLOR structures to translate. nColors - Contains the number of elements in the arrays pointed to by paInputColors and paOutputColors. ctInput - Specifies the input color type. Currently allowed: COLOR_UGRAY, COLOR_URGB. paOutputColors - Pointer to an array of nColors COLOR structures that receive the translated colors. ctOutput - Specifies the output color type. Currently allowed: COLOR_UGRAY, COLOR_URGB, SEE ALSO SetIDCMode()