Color Management

[This is preliminary documentation and subject to change.]

The increased use of color images in all forms of digital communication necessitates the implementation of a color management scheme for Windows® operating systems. The color management scheme that is used by Microsoft® Windows® 98 and Microsoft® Windows NT® 5.0 is called Image Color Management version 2.0, or ICM 2.0. To understand more about color management and ICM, information is divided into the following sections:

  • About Color Management
  • About Image Color Management Version 2.0
  • ICM 2.0 Reference


About Color Management

To understand how ICM 2.0 is used, a working knowledge of color management concepts is required. This overview presents enough color management background to provide a definition of the color management terms and concepts that appear in the ICM 2.0 Programmer's Reference in the Platform Software Development Kit (SDK) documentation. It is not exhaustive in its coverage. The topics in this section cover the major areas of color management, such as:

  • Color in Imaging
  • Color Spaces
  • Color Conversion And Color Management
  • Other Color Management Information Sources


Color In Imaging

Color management is not a new topic. It has been in common use for nearly as long as there have been commercial printing and publishing companies. A well-developed body of theory and experience has been applied in recent years to computerized imaging and publishing systems. The concepts embodied in these theories and practices are based on human color perception.

It is not necessary for application developers to possess a high level of expertise in the physiology of the eye and nervous system. Nor is it necessary to be an expert in the physics of light. However, an understanding of the fundamentals of vision and imaging will aid developers in using Image Color Management 2.0. These fundamentals include:

  • Human Color Perception
  • Additive Primary Colors
  • Subtractive Primary Colors
  • Describing Color


Human Color Perception

Human vision is made possible by the presence of light sensitive cells in the eye called rods and cones. Research has shown that the rods do not seem to be involved in the perception of color in human beings. There are three different types of cones in the retina. Each type of cone detects either red, green, or blue. All other colors we see are mixtures of these three colors. For instance, white is perceived when equal amounts of red, green, and blue are seen. Black is seen when no red, green, or blue (or no light at all) is detected by the eye. The amount of color we see also depends on the strength, concentration, and position of the light source. Lighting conditions can have a profound effect on the perception of color.

In imaging systems, colors can be mixed in different ways to produce a desired result for the eye. The mixing methods most commonly used are based on the additive primary colors and the subtractive primary colors. All colors can be reproduced using either method.


Additive Primary Colors

The additive method of color mixing is based on the assumption that you start with black. That is, if there are no other colors present (the image is black) and you add red, the image will appear red. If you then add blue. The image will appear magenta.

The three additive primary colors are red, green, and blue. The following figure illustrates additive primary color mixing.


Subtractive Primary Colors

The subtractive method of color mixing is based on the assumption that you start with white. All colors are present in equal amounts. If you subtract cyan and yellow from white, the resulting image is magenta. In a green image, subtracting cyan will result in changing the image to yellow.

The subtractive primary colors are cyan, yellow, and magenta. The following figure demonstrates subtractive primary color mixing.


Describing Color

Color can be described in terms of components. The components most often used by imaging professionals are hue, saturation, and brightness. A hue is what we normally think of as a color. A color's hue fixes its place in the visible spectrum of light. The saturation of a color is how "pure" or "strong" a color is. Neutral gray is said to have zero saturation. The brightness of a color refers to the intensity of light that is reflected or transmitted by an image.

The terms tint, tone, and shade are also well-used in color imaging literature. A tint of a color is obtained by mixing its hue with white. A tone of a color is created by mixing a hue with gray. A shade of a color is made by adding black to its hue.


Color Spaces

The human eye is often able to detect many more colors than digital devices can reproduce. For instance, if you look at a blank, white page of paper, your eye is probably detecting at least 100 distinct shades of white. A white wall can easily have 1500 shades of white.

High-quality digital cameras, scanners, and other image acquisition devices can also detect hundreds of thousands or even millions of colors. Because of the presence of so many detectable colors, imaging professionals have invented models for specifying colors. These models are called color spaces.

The reason these models are referred to as color spaces is that most of them can be mapped into a 2-D, 3-D, or 4-D coordinate system similar to a Cartesian coordinate system. Hence colors can be said to be composed of coordinates in a 2-D, 3-D, or 4-D space. The color components in a color space are also referred to as color channels.

Some color spaces are intended to be independent of any device that is used to produce color images. Some are very device dependent. Both device-dependent and device-independent color spaces are discussed in the following sections:

  • RGB Color Spaces
  • HSV Color Spaces
  • HLS Color Spaces
  • CMY and CMYK Color Spaces
  • Device-Dependent Color Spaces
  • Device-Independent Color Spaces


RGB Color Spaces

An RGB color space is created by mapping the colors red, green, and blue onto a 3-D Cartesian coordinate system. This results is a 3-D cube like the ones shown in the following figure. This figure displays the same RGB cube from two different angles. Notice that the origin of the coordinate system is black. This is where the red, green, and blue (RGB) color components are all 0.0. The diagonally opposite corner of the cube is white, where the RGB color components are at their maximum value.

Like most color spaces, the RGB color space is normalized. That is, all color values are restricted to the range of zero to one inclusive. So black is (0.0, 0.0, 0.0), and white is (1.0, 1.0, 1.0).

In the RGB color space, the primary colors are red, green, and blue. The secondary colors are cyan, yellow, and magenta.

RGB color spaces can be device dependent or device independent.


HSV Color Spaces

Hue, saturation, and value (HSV) color spaces are often used by artists. The hue is what we normally think of as color. Saturation is the amount of gray, white, or black that is mixed into the color. Zero saturation indicates no hue, just grayscale. The value component of the HSV space is a measure of its brightness. The HSV color space is normalized.

The preceding figure shows a line drawing of HSV space in the form of a hexcone. Each of its cross sections is a hexagon. At the vertices of each cross section are the colors red, yellow, green, cyan, blue, and magenta. A color in HSV space is specified by stating a hue angle, the saturation level, and the value level. A hue angle of zero is red. The hue angle increases in a counterclockwise direction. Complementary colors are 180° apart.

HSV color spaces can be device dependent or device independent.


HLS Color Spaces

HLS color spaces are also widely used by artists. Its color components are hue, lightness, and saturation.

Hue has the same meaning as the HSV model, except that a hue angle of 0° corresponds to blue in this model. Magenta is at 60°, red is at 120°. As with the HSV model, complementary colors are 180° apart.

Lightness is the amount of black or white in a color. Increasing lightness adds white to the hue. Decreasing lightness adds black to the hue.

Saturation in the HLS model is a measure of the "purity" of a hue. As saturation is decreased, the hue becomes more gray. A saturation value of zero results in a grayscale value.

The following figure is a line drawing of HLS space, which is a double hexcone. Any horizontal cross section of the HLS color space is a hexagon. HLS is a normalized color space. That is, the lightness and saturation values range from 0.0 to 1.0 inclusive. Hue varies from 0° to 360° inclusive.

HLS color spaces can be device dependent or device independent.


CMY and CMYK Color Spaces

The CMY and CMYK color spaces are often used in color printing. A CMY color space uses cyan, magenta, and yellow (CMY) as its primary colors. Red, green, and blue are the secondary colors.

The following figures are color representations of the CMY color space. The CMY color space is normalized.

The CMY color space is subtractive. Therefore, white is at (0.0, 0.0, 0.0) and black is at (1.0, 1.0, 1.0). If you start with white and subtract no colors, you get white. If you start with white and subtract all colors equally, you get black.

The CMYK color space is a variation on the CMY model. It adds black (Cyan, Magenta, Yellow, and blacK). The CMYK color space closes the gap between theory and practice. In theory, the extra black component is not needed. However, experience with various types of inks and papers has shown that when equal components of cyan, magenta, and yellow inks are mixed, the result is usually a dark brown, not black. Adding black ink to the mix solves this problem.

The CMY and CMYK colors spaces can be device independent, but most often they are used in reference to a specific device.


Device-Dependent Color Spaces

Most color spaces are device dependent. Even though a particular device, such as a monitor, may use the RGB color space, the colors it renders for given RGB values are often slightly different than all other types of monitors. It is precisely for this reason that the ICM 2.0 color management system is so useful.

All color spaces have a white point, which is defined as the whitest white that can be produced in that color space. Since each device is different, its white point is also different. All colors that a device can produce are relative to its white point. Therefore, a color management system must be able to map the white point of one color space into another and preserve the relative locations of all colors. It must also be able to map a color in one color space to its closest match in another color space regardless of the differences in the white points. ICM 2.0 is able to accomplish both of these tasks.

The RGB color space is often used on computer monitors. As such, it is device dependent. Printers typically use CMYK. Each printer implements its own version of the CMYK color space. Digital images may not actually store colors in them. They may store index numbers into a palette of colors. The result is that it is very hard for individual application developers to use or provide a standardized method of moving color images from one device to another. Imaging professionals commonly experience the frustration of creating a graphic image on a computer screen and having it turn out very differently when it is printed. ICM 2.0 addresses these imaging needs.


Device-Independent Color Spaces

Recognizing the need for standard, device-independent color measurements, the Commission International de l'Eclairage (International Commission on Illumination), or CIE, created a color space based on "imaginary" primary colors. No actual device is expected to produce colors in this color space. It is used as a means of converting colors from one color space to another. The primary colors in this color space are the abstract colors X, Y, and Z.

The CIE XYZ color space is widely used as the basis for color space conversion. With the rise of the Internet, however, bandwidth considerations have made the XYZ color space unwieldy. The exchange of images over the limited bandwidth of the Internet necessitates a more compact color model.

As a result, Hewlett-Packard and Microsoft have proposed the adoption of a standard predefined RGB color space known as sRGB, so as to allow accurate color management with very little data overhead. A white paper discussing the technical issues involved in sRGB is available on the Internet at:

http://www.color.org/contrib/sRGB.html

A help-file version of the white paper, sRGB.HLP, is also available in the \Help folder of the ICM 2.0 Programmer's Reference in the Platform SDK.

Different file formats may use or add a flag to specify that the image is in sRGB color space. In the Windows device-independent bitmap (DIB) format, setting the bV5CSType member of the BITMAPV5HEADER structure to LCS_sRGB specifies that the DIB colors are in the sRGB color space.


Color Conversion And Color Management

The process of converting colors from one color space to another is called color conversion. All colors in a color space are fixed relative to the color space's white point. Since the white point of a color space varies from device to device, a converted color must then be matched to its visually closest color in the destination color space. This process is called color mapping.

For example, if you have a digital image that you created on your display, it may be in a device-dependent RGB color space. If you want to print it on a printer, it must be converted to the printer's color space. Since the printer probably uses a device-dependent CMYK color space, all RGB values must be converted to CYMK. This is color conversion. Once the values are specified in terms of the CYMK space, they need to be matched to the closest color that the printer can produce. This is called color mapping or color matching.

Both color conversion and color mapping must take into account a number of device-specific factors. For instance, the building blocks of screen images are pixels. Each pixel has a set number of bits to store its color or color index value. The number of bits per pixel depends on the type of display and display adapter being used, and the mode to which that the adapter is set. Every printer type uses different inks and prints at particular resolutions.

In addition, the human eye may perceive the same colors differently on different devices. For instance, when colors are produced by computer monitors, they appear different than they would if they were produced on a printing press. A correction factor, called gamma correction, is used to compensate for such perceived differences.

The result of these device-dependent factors is that each color device has a particular set of colors that it can produce. This color set is known as its gamut. To perform color conversion and color mapping, the colors in an image must be converted from the color space and gamut of the source device into the color space of the destination device. They are then matched into the gamut of the destination device.


Other Color Management Information Sources

Further explanation of the terms and concepts discussed in this color management overview can be found in the following sources:

  • R.W.G. Hunt, Measuring Color, Prentice Hall 1991 (2nd edition).
  • James D. Foley, Computer Graphics: Principles and Practice, Addison-Wesley 1990 (2nd edition).
  • Roy Hall, Illumination and Color in Computer Generated Imagery, Springer Verlag 1988.
  • Fred W. Billmeyer, Jr. and Max Saltzmann, Principles of Color Technology, Wiley 1981 (2nd edition).

Another good source of information the Web page of the International Color Consortium (ICC) at URL: http://www.color.org. The membership of the ICC includes leaders and standard-setting bodies of the computer and imaging industries.


About Image Color Management Version 2.0

Microsoft Image Color Management (ICM) technology ensures that a color image, graphic or text object is rendered 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 paper, film, or other media, ICM 2.0 helps you keep its colors consistent and accurate.

ICM 2.0 is planned as an integral part of Microsoft Windows 98 and Windows NT 5.0. Because ICM 2.0 will be built into the Windows family of operating systems as a set of Win32® API functions, it will be readily available to any application, device driver, device calibration tool, or color management module (CMM).

What kinds of applications will benefit from using ICM 2.0? Almost any application running in a Windows environment today. Basic color management capability is becoming a requirement for applications of all kinds.

Color display and printing have improved in recent years to the point where photo-realistic color images and complex color graphics are now commonly used not only in desktop publishing, but also across a broad spectrum of data and presentation applications. Object technologies such as COM and ActiveX have embedded color objects in virtually every kind of data space.

Clothing catalogs, online art, family photo albums, business logos, charts, graphs, presentations, print previews, and color simulations are just a few examples of everyday applications where color matters.

As a result, more and more users are requiring their applications to be capable of accurate color display. Poor color rendering ruins the images and graphics that are increasingly important to users.

On a fundamental level, almost any application should be able to adjust color automatically so that its output looks the same on different monitors and printers. ICM 2.0 provides a set of functions to deliver this kind of color management that is transparent to a user and requires little overhead in the application.

On a higher level, ICM 2.0 provides additional functions that deliver more complex and controllable color management. Graphics and desktop publishing applications need these additional capabilities to let their users work precisely with consistent color across many devices throughout a production process.

In general, software vendors whose products deal with color input or output and hardware vendors of color peripherals will find ICM 2.0 a key technology for simplifying the delivery of successful products. The following sections include:

  • What's New in Version 2.0 of ICM
  • ICM 2.0 Availability
  • Installing ICM 2.0
  • ICM 2.0 Fundamentals
  • ICMView: A Sample Application


What's New in Version 2.0 of ICM

Version 1.0 of Image Color Management (ICM) was delivered in Microsoft Windows 95, and provides basic color management capabilities within Windows device contexts.

ICM Version 2.0 is planned for delivery in Windows 98 and Windows NT 5.0, and includes a variety of new functions that implement color management outside of device contexts. These new functions are suitable for more demanding color management requirements, and give applications greater control over the color-management process.

A Common Dialog for Color Management

[This is preliminary documentation and subject to change.]

One new feature of ICM 2.0 is the common dialog box that is available to applications through the SetupColorMatching function. This dialog box gives users control over color management options, using the following interface.

The dialog box managed by SetupColorMatching should appear when Color Management is chosen on the File menu. The default dialog box looks like the following:

The default information that appears in this dialog box is provided by the application. If no information is provided by the application, then the dialog box uses the default monitor color space provided by the system. If no monitor color space is available, the sRGB color space is assumed.

The Enable Color Management check box lets the user enable or disable color management on the system.

The Monitor Profile list box lets the user select a color profile for the monitor from the list of available profiles associated with that monitor. The default profile is the system default profile for the current monitor.

The Rendering Intent list box lets the user choose a rendering intent. Possible rendering intents are:

Intent | Description
Perceptual | For images and photographs; attempts to maintain the relationship between colors.
Saturated | For charts and business graphics; attempts to maintain a color's saturation, rather than its hue or lightness.
Relative Colorimetric | Does not preserve the white point; if the output gamut does not support a given color, the nearest supported color is used.
Absolute Colorimetric | Preserves the white point; if the output gamut does not support a given color, the nearest supported color is used.

The default intent is "Perceptual." For more information, see Rendering Intents.

The Printer Profile list box lets the user select a specific profile for the current printer. The default value that appears in this box should always be the default profile for the current printer's current configuration.

The Proofing check box lets a user enable soft or hard proofing.

When proofing is enabled, the Target Profile list box defaults to the current printer profile. However, all profiles installed on the system are available in this list box.

When proofing is enabled, the Rendering Intent list box under Proofing defaults to the intent set in the Rendering Intent list box. The upper Rendering Intent list box is set to the Absolute Colorimetric intent. The user may select a different proofing intent. It would be very unusual, however, for a user to select anything other than Absolute Colorimetric in the upper list box at this time.

A callback function can be supplied to ICM that enables configuration information to be applied immediately to a device. For details see ApplyCallbackFunction. If the callback function is provided to ICM, the Color Management dialog box will have one additional button, labeled Apply, shown in the following figure. Every time the user selects the Apply button, the callback function is invoked.


ICM 2.0 Availability

ICM 2.0 is available for Microsoft Windows 98, and for Windows NT 5.0. It is not available for MS DOS®, Windows 3.x, Windows 95, or any version of Windows NT prior to version 5.0.


Installing ICM 2.0

Note ICM 2.0 is not available under Windows 95 or Windows NT 4.0.

In order to run programs that use ICM 2.0, you must have the correct version of Windows running on your system. See ICM 2.0 Availability for details.

Downloading and Installing ICM 2.0

The ICM 2.0 beta documentation can be downloaded from the following World Wide Web site on the Internet:

http://www.microsoft.com/msdn/sdk/icm20.htm

From this site, you can download Wicm20.exe which is a self-extracting installation file. After you have downloaded this file to your local development system, you can install the Programmer's Reference by running it as a program.

Your test machine must be running the beta 1 release of either Windows 98 or Windows NT 5.0. Copy the updated ICM 2.0 dynamic-link libraries to the test machine after you have installed the Programmer's Reference on your development system, using the following procedure.

Updating your Windows Beta Machine

Note This Programmer's Reference requires the beta 1 release of Windows 98 or the beta 1 release of Windows NT 5.0.

To Update Dynamic-Link Libraries on your Windows Beta Machine
  1. Copy the following file from the \Lib folder of the ICM 2.0 Programmer's Reference into the Windows system folder on the beta machine:
    • Icmui.dll
  2. Copy the file Icm.inf from the ICM 2.0 Programmer's Reference root folder to the desktop or to a temporary folder on your beta machine.
  3. Right click on the Icm.inf file and select Install from the menu that appears. This updates the registry on your beta machine to take advantage of the new DLL files.


ICM 2.0 Fundamentals

This section presents an overview of how ICM 2.0 works, and how it can be used to create applications that utilize color management. It contains the following topics:

  • Using Device Profiles with ICM
  • Using Color Management Modules (CMM)
  • Rendering Intents
  • Using The Color Mapping Process with ICM
  • Using Structures in ICM 2.0
  • Using Color Management on the Internet


Using Device Profiles with ICM

Device profiles are a basic tool for color management. A device profile is a file that contains information about how to convert colors in the color space and the color gamut of a specific device into a device-independent color space. The device-independent color space that ICM uses is called a Profile Connection Space (PCS). A device profile also contains information about how to convert colors from the PCS into the color space and color gamut of a specific device.

These two sets of conversion information are used for color conversion and color management. For instance, an image may be created in the color space and color gamut of a video display. The information in the device profile files can be used to display a representation of a printed image. Users often want to see on the screen how colors will change when an image is printed. This is called proofing. An image can be proofed by converting the colors from the source color gamut (the screen) into PCS colors, and then converting them from the PCS into the destination color gamut (the printer). The resulting image can be displayed on the screen, allowing the user to see what the final image will look like when it is printed.

Device profiles allow more complex uses as well. For example, they can be used to get an idea of what an image created on a video display would look like when printed on a high resolution laser printer. The example gets more complex if there is only a standard inkjet printer on which to proof it. ICM will convert the image from the gamut of the display, into the gamut of the inkjet printer. From there it is converted into the gamut of the laser printer. The resulting image can be printed on the inkjet printer. Of course the image would be at a higher resolution when printed on the color laser printer. However, the colors of the proofing image printed on the inkjet printer would be a close match to the colors that the laser printer would print.

The conversions from a device profile can be concatenated together into a single file, called a device link profile. If a series of conversions is used repeatedly, creating a device link profile for them will shorten conversion time.

Device profiles themselves can be managed. Profile management is the process of associating color profiles with device instances. Any color output device can have a set of one or more color profiles associated with it. Hardware manufacturers and third parties who provide color profiles need to perform profile management.

Profile sets can be shared between devices, or can be dedicated to specific devices. For example, suppose that you have two color printers of the same model. Each printer would require a set of color profiles to be associated with it. The set of color profiles for a printer corresponds to the various configurations possible in that model. Being of the same model, both printers could share one set of profiles. The alternative is to give each printer its own distinct profile set. In the latter case, the color profiles in the set can be calibrated precisely to the printer's individual output, not just the general output characteristics of the model.

There are three different classes of ICC profiles: input profiles, display profiles, and output profiles. Input profiles are usually associated with a device, such as a scanner. Display profiles are typically associated with a computer monitor. Output profiles are commonly associated with printers.

The specification also allows for device profiles, abstract profiles, device link profiles, named color profiles, and color space profiles.

A device profile describes the color space of a particular device.

An abstract profile provides a generic method for users to make subjective color changes to images or graphic objects by transforming the color data within the PCS.

As mentioned previously, a device link profile concatenates a series of profiles into one transformation.

Named color profiles can be thought of as sibling profiles to device profiles. For a given device there would be one or more device profiles to handle process color conversions and one or more named color profiles to handle named colors. There might be multiple named color profiles to account for different consumables or multiple named color vendors.

A color space profile describes a device-independent color space.

The following table summarizes the various types of profiles.

Profile Type | Description
Abstract Profile | A profile that has been adjusted to suit a user's particular preferences.
Color Space Profile | A profile that describes a device-independent color space.
Device Link Profile | A series of profiles that are concatenated together into a single profile.
Device Profile | A profile that describes the color space of a particular device.
Display Profile | A class or category of profiles that includes any type of profile associated with a display.
Input Profile | A class or category of profiles that includes any type of profile associated with an input device such as a scanner.
Named Color Profile | A profile for a color space that consists of named colors.
Output Profiles | A class or category of profiles that includes any type of profile associated with a hardcopy output device such as a printer.

Color transforms can be created with one or more profiles. If a transform is created with only one profile, the profile must be a device link profile. A transform may also have two or more profiles in a chain. If it does, it can contain no device link profiles. Abstract profiles can only be in the middle of the chain. The first and last profiles must be device profiles or color space profiles.


Using Color Management Modules (CMM)

Color Management Modules (CMMs) are modules of ICM code that use the information in device profiles to do color conversion and color mapping. Application developers should not have to implement CMMs. Microsoft provides the default CMM. However, if you do write software that requires the use of specialized color conversion and color mapping algorithms, you may create one.

Note CMM entry points are not API functions and should not be called by applications.


Rendering Intents

The International Color Consortium (ICC) has defined four different values called rendering intents. These represent four different approaches to creating a color rendering. These four intents, and the constants used to refer to them in code are as follows.

Intent | Constant
Perceptual | INTENT_PERCEPTUAL
Saturation | INTENT_SATURATION
Relative Colorimetric | INTENT_RELATIVE_COLORIMETRIC
Absolute Colorimetric | INTENT_ABSOLUTE_COLORIMETRIC

The ICC Profile Format Specification Version 3.3, which describes these intents, can be downloaded from the following Internet address:

http://www.color.org

Perceptual Intent

According to the ICC specification, clause 4.9, a perceptual intent causes the full gamut of the image to be compressed or expanded to fill the gamut of the destination device, so that gray balance is preserved but colorimetric accuracy may not be preserved.

In other words, if certain colors in an image fall outside of the range of colors that the output device can render, a perceptual intent will cause all the colors in the image to be adjusted so that the every color in the image falls within the range that can be rendered and so that the relationship between colors is preserved as much as possible.

This intent is most suitable for display of photographs and images, and is generally the default intent.

Saturation Intent

According to the ICC specification, clause 4.11, a saturation intent preserves the saturation of colors in the image at the possible expense of hue and lightness.

Implementation of this intent remains somewhat problematic, and the ICC is still working on methods to achieve the desired effects.

This intent is most suitable for business graphics such as charts, where it is more important that the colors be vivid and contrast well with each other than that they be accurate.

Relative Colorimetric Intent

In a colorimetric intent, any colors that fall outside the range that the output device can render are adjusted to the closest color that can be rendered, while all other colors are left unchanged.

Relative colorimetric intent does not preserve the white point.

For example, the whitest white of a paper is more yellow than the whitest white of a computer monitor. An image converted into the gamut of the printer using relative calorimetric intent would result in all colors becoming more yellow. The white point of the image is moved to match the white point of the printer. All other colors in the image keep their position relative to the white point. This produces an image that more accurately reflects what the printed image will look like. However, the user may find it visually disconcerting.

Absolute Colorimetric Intent

In a colorimetric intent, any colors that fall outside the range that the output device can render are adjusted to the closest color that can be rendered, while all other colors are left unchanged.

Absolute colorimetric intent preserves the white point.

For example, the whitest white of a paper is more yellow than the whitest white of a computer monitor. An image converted into the gamut of the printer using absolute calorimetric intent would result in all colors being converted and matched into the gamut of the printer. The white point of the image is not moved to match the white point of the printer. Therefore, the distance of the colors to the white point may change. This produces an image that is less visually disconcerting to the user, but is also a less accurate rendition of printer output.


Using The Color Mapping Process with ICM

ICM color mapping is based on device profiles. These are supplied by vendors of color hardware devices and installed when a device is installed. When color mapping is used by an application program, ICM accesses the device profile of the image to get the information needed to convert the image to the PCS. The conversion is done by the CMM.

A device profile can be embedded into the image itself. So the device profile travels with the image, even across the Internet. A user does not need the source device to get an accurate color mapping. If an image does not have a device profile, the sRGB space is used as a default. For more details, see Using Color Management on the Internet.

Note that applications which use ICM should never embed the sRGB profile into an image. The sRGB color space provides a standardized color space that is portable across all devices. It is automatically available to users of Windows 98 and Windows NT. Therefore, it does not need to travel with the image.

After the image colors are in the PCS, ICM accesses the device profile of the destination device. It gets the CMM to convert the image colors from PCS to the gamut of the destination device.

More complex color mapping can also be done with ICM. For example, it can be used to get an idea of what an image created on a video display would look like when printed on a high resolution laser printer. The example gets more complex if there is only a standard inkjet printer on which to preview it. The image can be converted from the gamut of the display, into the gamut of the inkjet printer. From there it can converted into the gamut of the laser printer. The resulting image can be printed on the inkjet printer. Of course the image would be at a higher resolution when printed on the color laser printer. However, the colors of the proofing image printed on the inkjet printer would be a close match to the colors that the laser printer would print.

The way the conversions in the example are accomplished is to covert the image colors from the display's gamut into the PCS. After the image colors are converted into the PCS, the device profile of the inkjet printer would be used to transform them into the gamut of the inkjet printer. Next, the gamut to PCS transform would be used to move the colors back to the PCS. From there, the laser printer's device profile is used to convert the colors from PCS into the gamut of the laser printer.

The ability to easily transform colors from a device gamut to the PCS and back again enables image colors intended for one color output device to be proofed on almost any other.

In the preceding example, the description varies from the actual procedure somewhat for clarity. In reality, all of the transformations mentioned in the preceding paragraph would be concatenated into a single transformation.


Using Structures in ICM 2.0

Most of the structures used by ICM 2.0 are very straightforward and require little explanation. They are documented in the ICM 2.0 Reference section entitled ICM 2.0 Structures.

Exceptions are the COLORMATCHSETUP structure used by the SetupColorMatching function, and the following Windows structures defined in Wingdi.h:

  • BITMAPV5HEADER
  • LOGCOLORSPACE
  • CIEXYZ
  • CIEXYZTRIPLE

The following topics are discussed at greater length:

  • Windows Bitmap Header Structures
  • Differences Between V4 and V5 Headers
  • Bitmap.exe: a Command-Line Utility for Converting Bitmap Headers

Windows Bitmap Header Structures

[This is preliminary documentation and subject to change.]

ICM 2.0 allows ICC color profiles to be linked or embedded in device-independent bitmaps (DIBs). This allows DIB colors to be characterized more accurately than was possible using ICM in Windows 95. BITMAPV5HEADER, the new bitmap header structure, is defined in Wingdi.h in the release of Windows 98. For development purposes, it is also included in the file Icm.h with this Programmer's Reference. The BITMAPV5HEADER structure is as follows:

typedef struct {
   DWORD        bV5Size;
   LONG         bV5Width;
   LONG         bV5Height;
   WORD         bV5Planes;
   WORD         bV5BitCount;
   DWORD        bV5Compression;
   DWORD        bV5SizeImage;
   LONG         bV5XPelsPerMeter;
   LONG         bV5YPelsPerMeter;
   DWORD        bV5ClrUsed;
   DWORD        bV5ClrImportant;
   DWORD        bV5RedMask;
   DWORD        bV5GreenMask;
   DWORD        bV5BlueMask;
   DWORD        bV5AlphaMask;
   DWORD        bV5CSType;
   CIEXYZTRIPLE bV5Endpoints;
   DWORD        bV5GammaRed;
   DWORD        bV5GammaGreen;
   DWORD        bV5GammaBlue;
   DWORD        bV5Intent;         // Rendering intent for bitmap
   DWORD        bV5ProfileData;    // Offset to profile data
   DWORD        bV5ProfileSize;    // Size of embedded profile data
   DWORD        bV5Reserved;       // For future use - should be zero
} BITMAPV5HEADER, FAR *LPBITMAPV5HEADER, *PBITMAPV5HEADER;

The member bV5CSType can have the values PROFILE_EMBEDDED or PROFILE_LINKED to specify whether a profile is embedded or linked with the DIB. The member bV5ProfileData is the offset in bytes from the beginning of the BITMAPV5HEADER structure to the start of the profile data. If the profile is embedded, profile data is the actual profile, and if it is linked, the profile data is the null-terminated file name of the profile. This cannot be a Unicode string. It must be composed exclusively of characters from the Windows character set (code page 1252).

When a DIB is loaded into memory, the profile data (if present) should follow the color table, and bV5ProfileData should give the offset of the profile data from the beginning of the BITMAPV5HEADER structure. The value of this member will be different now, as the bitmap bits do not follow the color table in memory. Applications should modify the bV5ProfileData member after loading the DIB into memory.

For packed DIBs, the profile data should follow the bitmap bits similar to the file format. The bV5ProfileData member should still give the offset of the profile data from the beginning of the BITMAPV5HEADER structure.

Applications should access the profile data only when bV5Size == sizeof(BITMAPV5HEADER) AND bV5CSType is PROFILE_EMBEDDED or PROFILE_LINKED.

If a profile is linked, the path of the profile can be any fully qualified name (including a network path) that can be opened using the Win32 CreateFile function.

Differences Between V4 and V5 Headers

In working with the new bitmap structure, it is useful to recognize differences in how BITMAPV4HEADER and BITMAPV5HEADER structures are set up:

V4 Header

  1. bV4CSType = LCS_CALIBRATED_RGB. This value implies that end points and gammas are given in the appropriate fields. Bogus values cause trouble.
  2. bV4CSType = LCS_sRGB. This value implies that the bitmap is in sRGB color space (gammas and endpoints ignored).
  3. bV4CSType = LCS_WINDOWS_COLOR_SPACE. This value implies that the bitmap is in Windows default color space.

V5 Header

  1. bV5CSType = LCS_CALIBRATED_RGB. This value implies that end points and gammas are given in the appropriate fields. Bogus values cause trouble.
  2. bV5CSType = LCS_sRGB. This value implies that the bitmap is in sRGB color space (gammas and endpoints ignored).
  3. bV5CSType = PROFILE_EMBEDDED. This value implies that bV5ProfileData points to a memory buffer that contains the profile to use (gammas and endpoints are ignored).
  4. bV5CSType = PROFILE_LINKED. This value implies that bV5ProfileData points to the file name of the profile to use (gammas and endpoints are ignored).
  5. bV5CSType = LCS_WINDOWS_COLOR_SPACE. This value implies that the bitmap is in Windows default color space.

In order to convert older bitmaps to and from the new BITMAPV5HEADER structure, a command-line conversion utility file named Bitmap.exe is included in the ICM 2.0 Programmer's Reference.

BitMap.exe: a Command-Line Utility for Converting Bitmap Headers

Bitmap.exe is a command-line utility located in the \Bin folder under the installation folder that you specified. It modifies the headers of Windows bitmaps, allowing you to convert existing bitmaps from BITMAPINFOHEADER and BITMAPV4HEADER header structures to the newer BITMAPV5HEADER structure and back again. The command-line syntax is as follows:

BITMAP [/d] [/1|4|5] [/s] [/f] filename

The command-line switches have the following effects.

 | Meaning
/d | Default values are automatically entered in the converted headers.
/1 | Convert the specified bitmaps to BITMAPINFOHEADER
/4 | Convert the specified bitmaps to BITMAPV4HEADER
/5 | Convert the specified bitmaps to BITMAPV5HEADER
/f | Forces conversion, even if the bitmap already has the right header
/s | Converts bitmaps in the specified folder and all subdirectories under it


Using Color Management on the Internet

Color images and graphics are an increasingly important way of communicating information for users of the Internet. Color conversion information can be embedded in some file formats. The embedding techniques currently used are not compact. Internet bandwidth considerations often make them impractical. Internet considerations include the following topics:

  • sRGB: A Proposed Standard Color Space
  • ICM 2.0 Defaults for Input Color Space and Output Profile
  • sRGB and Embedded Profiles

sRGB: A Proposed Standard Color Space

As a result of Internet bandwidth considerations, Hewlett-Packard and Microsoft have proposed the adoption of a standard predefined color space known as sRGB, so as to allow accurate color mapping with very little data overhead. A white paper discussing the technical issues involved in sRGB is available on the Internet at:

http://www.color.org/contrib/sRGB.html

A help-file version of the white paper, sRGB.hlp, is also available in the \Help folder of the ICM 2.0 Programmer's Reference.

Different file formats may use or add a flag to specify that the image is in sRGB color space. In the Windows device-independent bitmap (DIB) format, setting the bV5CSType member of the BITMAPV5HEADER structure to LCS_sRGB specifies that the DIB colors are in the sRGB color space.

ICM 2.0 provides native support for sRGB. There are two ways to use ICM 2.0 for rendering an image defined in the sRGB color space:

  • Inside the device context:
    1. Create a device context (DC) on the display device.
    2. Set color management using the SetICMMode function.
    3. Use the SetDIBitsToDevice function to transfer the DIB into the DC. As long as the bV5CSMType member of the DIBs BITMAPV5HEADER structure is set to LCS_sRGB, the system will perform the appropriate color management.
  • Outside the device context:
    1. Create a transform using CreateColorTransform. The lcsCSType member of the LOGCOLORSPACE structure pointed to by the pLogColorSpace parameter should be set to LCS_sRGB. The hDestProfile parameter indicates the display device's color space.
    2. Use the created color transform to color match the image before displaying it on the device.

ICM 2.0 Defaults for Input Color Space and Output Profile

When no input color space is specified, by default ICM 2.0 uses the sRGB color space as the input color space for color mapping.

When no output profile is specified, but a default device is specified, ICM 2.0 selects a default output profile. If the default device does not have an associated profile, ICM 2.0 uses the sRGB color space as the output profile.

The following table shows the resulting color transforms when a default device is not available.

 | Output Profile Specified | Output Profile Not Specified
Input Color Space Specified | Transform uses the specified profiles. | Transform converts from known input color space to sRGB.
Input Color Space Not Specified | Transform converts from sRGB to known output profile. | Transform from sRGB to sRGB is assumed; nothing is done.

sRGB and Embedded Profiles

Applications that utilize ICM can embed profiles in images. Embedded profiles assist users' applications in maintaining a consistent color appearance even if images are transmitted across the Internet. One of the primary advantages of the sRGB color space is that it is readily available on all versions of Windows and Windows NT that support ICM (For information on which versions of Windows and Windows NT provide ICM support, see ICM 2.0 Availability).

Images that use the sRGB color space do not need an embedded color profile. Because they have no embedded profile, sRGB-based images are smaller and more readily transferable across data channels with limited bandwidth.

Applications should set the LCS_sRGB flag in the image's bitmap header to indicate that the image uses the sRGB color space. For details, see Windows Bitmap Header Structures and LOGCOLORSPACE.


Using GDI Functions With ICM

There are various functions in the graphics device interface (GDI) that use or operate on color data. Some are enabled for use with ICM and some are not. The following GDI functions are relevant to ICM:

  • Device Context Functions with ICM
  • Pen And Brush Functions with ICM
  • Text Output Functions with ICM
  • Bitmap Functions with ICM

Device Context Functions with ICM

CreateCompatibleDC
If the device context (DC) that is passed to this function through its hdc parameter is enabled for ICM, then the DC the function creates is also ICM-enabled. The source and destination color spaces are specified in the DC.
CreateDC
ICM can be enabled by setting the dmICMMethod member of the DEVMODE structure pointed to by the pInitData parameter to the appropriate value. For details, see the documentation in the Platform SDK on the DEVMODE structure.
ResetDC
The color profile of the device context specified by the hdc parameter will be reset based on the information in the DEVMODE structure specified by the lpInitData parameter.

Pen And Brush Functions with ICM

Brush Functions
No color management is done at brush creation. However, color management will be performed when the brush is selected into an ICM-enabled DC.
CreatePen
No color management is done at pen creation. However, color management will be performed when the brush is selected into an ICM-enabled DC.
ExtCreatePen
No color management is done at pen creation. However, color management will be performed when the brush is selected into an ICM-enabled DC.
SelectObject
If the object being selected is a brush or a pen, color management is performed.
SetDCBrushColor
Color management is performed if ICM is enabled.
SetDCPenColor
Color management is performed if ICM is enabled.

Text Output Functions with ICM

SetBkColor
Color management is performed if ICM is enabled.
SetTextColor
Color management is performed if ICM is enabled.

Bitmap Functions with ICM

BitBlt
No color management is performed when blits occur.
CreateDIBitmap
The fuUsage parameter specifies that the bmiColors member of the BITMAPINFO structure pointed at by the lpbmi parameter does or does not contain color information. If it does not, no color management is performed for this bitmap. The bitmap must use version 4 or version 5 of the BITMAPINFO structure for color management to be enabled. The contents of the resulting bitmap are not color matched after the bitmap has been created.
CreateDIBSection
If the BITMAPINFO structure passed through the pbmi parameter is not version 4 or version 5, no color management is done. If it is version 4 or 5, color management is enabled, and the specified color space is associated with the bitmap.
MaskBlt
No color management is performed when blits occur.
SelectObject
If the object is a bitmap created with CreateDIBSection, color management is performed. The bitmap's color space is used as the destination color space.
SetDIBits
Color management is performed. If the specified BITMAPINFO structure is not version 4 or version 5, the color profile of the current DC is used as the source color space profile. If it does not have one, the sRGB space is used. If the specified BITMAPINFO structure is version 4 or version 5, the color space profile specified in the bitmap header is used as the source color space profile.
SetDIBitsToDevice
Color management is performed. If the specified BITMAPINFO structure is not version 4 or version 5, the color profile of the current device context is used as the source color space profile. If it doesn't have one, the sRGB color space is used. If the specified BITMAPINFO structure is version 4 or version 5, the color space profile associated with the bitmap is used as the source color space.
SetDIBColorTable
No color management is performed.
StretchBlt
No color management is performed when blits occur.
StretchDIBits
Color management is performed. If the specified BITMAPINFO structure is not version 4 or version 5, the color profile of the current DC is used as the source color space profile. If it does not have one, the sRGB space is used. If the specified BITMAPINFO structure is version 4 or version 5, the color space profile specified in the bitmap header is used as the source color space profile.


ICMView: A Sample Application

The ICM 2.0 Programmer's Reference includes a sample application, ICMView. It serves both as a functioning application for demonstrating what color mapping accomplishes, and a programming example illustrating the use of many of the ICM 2.0 functions.

ICMView is unusual in that it implements color management both inside and outside of the device context. This is helpful for demonstration purposes, but not characteristic of most real-world applications. In general, an application would be likely to use one strategy or the other, not both.

Much of the sample code is dedicated to creating a normal Windows application. Of particular interest to programmers concerned with color management using ICM 2.0 are the user-defined DIBPaint function in Dibs.c and the user-defined PrintImage function in Print.c.

DIBPaint illustrates using ICM functions to perform color management within a device context. PrintImage, on the other hand, performs color management outside the device context. It is worth noting that in a more complex application, the printer output profile should be reset every time an end-of-page occurs.


ICM 2.0 Reference

The API elements that ICM provides fall into the following sections:

  • ICM 2.0 Functions
  • Obsolete ICM Functions
  • ICM 2.0 Enumerations
  • ICM 2.0 Structures
  • Macros for CMYK Values and Colors
  • Common Color Messages
  • Error Codes Specific To ICM


ICM 2.0 Functions

In the ICM 2.0 function reference, ICM functions are organized by category. This allows you to browse among functions that have related uses. In later releases of this information, these functions are more likely to appear in alphabetical order in the Platform SDK documentation.

The functions are grouped as follows:

  • Basic ICM 2.0 Functions for Use Within a Device Context
  • Advanced ICM 2.0 Functions for Use Outside of a Device Context
  • Device Calibration and Characterization Functions in ICM 2.0
  • Profile Management Functions in ICM 2.0
  • ICM Functions for Color Management Modules (CMMs) to Implement
  • Alphabetical List of All ICM 2.0 API Functions


Basic ICM 2.0 Functions for Use Within a Device Context

The following ICM functions deliver basic color mapping capabilities within device contexts. They are useful to all applications that need to implement color management with low overhead and minimal user intervention.

Function | Description
CheckColorsInGamut | Checks if given colors are in a device's gamut.
ColorCorrectPalette | Corrects the entries in a palette for a device context.
ColorMatchToTarget | Performs color mapping for preview purposes.
CreateColorSpace | Creates a color space.
DeleteColorSpace | Deletes a color space.
EnumICMProfiles | Enumerates output color profiles available for a given device context.
EnumICMProfilesProcCallback | Application-defined callback function for EnumICMProfiles. The name of this function is also defined by the application.
GetColorSpace | Gets the current input color space in a device context.
GetICMProfile | Gets the current output color profile of a device context.
GetLogColorSpace | Gets the LOGCOLORSPACE structure of a device context.
SetColorSpace | Sets a device context's input color space.
SetICMMode | Turns color management on or off in a device context.
SetICMProfile | Sets the output color profile for a given device context.


Advanced ICM 2.0 Functions for Use Outside of a Device Context

These functions, currently planned for the new releases of Microsoft® Windows® 98 and Microsoft® Windows NT® 5.0, provide advanced color management capabilities outside of device contexts.

Function | Description
CheckBitmapBits | Checks bitmap colors against a gamut.
CheckColors | Checks colors against a device output gamut.
ConvertColorNameToIndex | Converts color names in a named color space to index numbers in a color profile.
ConvertIndexToColorName | Converts indices in a color space to an array of names in a named color space.
CreateColorTransform | Creates a color transform.
CreateMultiProfileTransform | Creates a transform from multiple profiles.
DeleteColorTransform | Deletes a color transform.
GetCMMInfo | Identifies the CMM that created a transform.
GetNamedProfileInfo | Retrieves information about a named color profile.
ICMProgressProcCallback | Application-supplied callback function to report progress. The name of this function is also defined by the application.
SelectCMM | Specifies a preferred CMM to use.
SetupColorMatching | Provides user control over color management by way of a dialog box.
TranslateBitmapBits | Converts bitmap colors using a color transform.
TranslateColors | Converts colors using a color transform.


Device Calibration and Characterization Functions in ICM 2.0

The following functions are useful for writing device calibration and characterization tools needed for installing and calibrating color display devices such as monitors and printers.

Function | Description
CloseColorProfile | Closes a profile.
CreateDeviceLinkProfile | Creates an ICC device-link profile.
GetColorProfileElement | Retrieves data from a given profile element.
GetColorProfileElementTag | Retrieves the tag name from a profile element.
GetColorProfileFromHandle | Retrieves the color profile contents given a handle to an open color profile.
GetColorProfileHeader | Retrieves the header from a profile.
GetCountColorProfileElements | Counts the tagged elements in a profile.
GetPS2ColorRenderingDictionary | Gets a PostScript color rendering dictionary.
GetPS2ColorRenderingIntent | Gets a PostScript color rendering intents.
GetPS2ColorSpaceArray | Gets a PostScript color space from a profile.
IsColorProfileTagPresent | Checks that a given tag is present in a profile.
IsColorProfileValid | Checks that a profile is a valid ICC profile.
OpenColorProfile | Opens a profile and returns a handle to it.
SetColorProfileElement | Writes data for a given profile element.
SetColorProfileElementReference | Creates a tag that refers to existing tag data.
SetColorProfileElementSize | Sets the size of a given profile element.
SetColorProfileHeader | Sets the header information in a given profile.


Profile Management Functions in ICM 2.0

The following ICM 2.0 API functions are useful in profile management.

Function | Description
AssociateColorProfileWithDevice | Associates a color profile with a device.
CreateProfileFromLogColorSpace | Converts a LOGCOLORSPACE to a device profile.
DisassociateColorProfileFromDevice | Disassociates a color profile from a device.
EnumColorProfiles | Enumerates color profiles satisfying specified criteria.
GetColorDirectory | Identifies the system color directory.
GetDeviceGammaRamp | Gets the gamma ramp from direct color display boards.
GetStandardColorSpaceProfile | Retrieves a registered standard space profile.
InstallColorProfile | Installs a color profile for use in the system.
RegisterCMM | Registers a CMM for use by the system. Used to install new CMMs.
SetDeviceGammaRamp | Sets the gamma ramp on direct color display boards.
SetStandardColorSpaceProfile | Registers a profile for a standard color space.
UninstallColorProfile | Uninstalls a color profile from the system.
UnregisterCMM | Removes the CMM registration. Used to uninstall new CMMs.


ICM Functions for Color Management Modules (CMMs) to Implement

The following functions are to be implemented by color management modules (CMMs), and exported for the operating system to call.

Function | Description
CMCheckColors | Checks colors against an output gamut.
CMCheckColorsInGamut | Checks RGB triplets against an output gamut.
CMCheckRGBs | Checks bitmap colors against an output gamut.
CMConvertColorNameToIndex | Converts color names in a named color space to index numbers in a color profile.
CMConvertIndexToColorName | Converts indices in a color space to an array of names in a named color space.
CMCreateDeviceLinkProfile | Creates an ICC device link profile.
CMCreateMultiProfileTransform | Creates a transform from an array of profiles.
CMCreateProfile | Creates an ICC profile from a LOGCOLORSPACE structure (ANSI).
CMCreateProfileW | Creates an ICC profile from a LOGCOLORSPACE structure (Unicode).
CMCreateTransform | Creates a color transform (ANSI).
CMCreateTransformExt | Creates an extended color transform (ANSI).
CMCreateTransformExtW | Creates an extended color transform (Unicode).
CMCreateTransformW | Creates a color transform (Unicode).
CMDeleteTransform | Deletes a color transform.
CMGetInfo | Returns information about a given CMM.
CMGetNamedProfileInfo | Retrieves information about a named color profile.
CMGetPS2ColorRenderingDictionary | Gets a PostScript color rendering dictionary.
CMGetPS2ColorRenderingIntent | Gets a PostScript color rendering intent.
CMGetPS2ColorSpaceArray | Gets a PostScript color space array.
CMIsProfileValid | Checks that a profile is a valid ICC profile.
CMTranslateColors | Translates colors using a color transform.
CMTranslateRGB | Translates an RGB color using a color transform.
CMTranslateRGBs | Translates bitmap colors using a color transform.
CMTranslateRGBsExt | Translates bitmap colors with callback progress reporting.


Alphabetical List of All ICM 2.0 API Functions

The following is a complete alphabetical list of the ICM 2.0 API functions provided by Windows and Windows NT.

Function or Structure | Description
ApplyCallbackFunction | Callback function that can be used to update ICM configuration data.
AssociateColorProfileWithDevice | Associates a color profile with a device.
CheckBitmapBits | Checks bitmap colors against a gamut.
CheckColors | Checks colors against a device output gamut.
CheckColorsInGamut | Checks if given colors are in a device's gamut.
CloseColorProfile | Closes a profile.
CMCheckColors |  | Checks colors against an output gamut.
CMCheckColorsInGamut |  | Checks RGB triplets against an output gamut.
CMCheckRGBs |  | Checks bitmap colors against an output gamut.
CMConvertColorNameToIndex |  | Converts color names in a named color space to index numbers in a color profile.
CMConvertIndexToColorName |  | Converts indices in a color space to an array of names in a named color space.
CMCreateDeviceLinkProfile |  | Creates an ICC device link profile.
CMCreateMultiProfileTransform |  | Creates a transform from an array of profiles.
CMCreateProfile |  | Creates an ICC profile from a LOGCOLORSPACE structure (ANSI).
CMCreateProfileW |  | Creates an ICC profile from a LOGCOLORSPACE structure (Unicode).
CMCreateTransform |  | Creates a color transform (ANSI).
CMCreateTransformExt |  | Creates an extended color transform (ANSI).
CMCreateTransformExtW |  | Creates an extended color transform (Unicode).
CMCreateTransformW |  | Creates a color transform (Unicode).
CMDeleteTransform |  | Deletes a color transform.
CMGetInfo |  | Returns information about a given CMM.
CMGetNamedProfileInfo |  | Retrieves information about a named color profile.
CMGetPS2ColorRenderingDictionary |  | Gets a PostScript color rendering dictionary.
CMGetPS2ColorRenderingIntent |  | Gets a PostScript color rendering intent.
CMGetPS2ColorSpaceArray |  | Gets a PostScript color space array.
CMIsProfileValid |  | Checks that a profile is a valid ICC profile.
CMTranslateColors |  | Translates colors using a color transform.
CMTranslateRGB |  | Translates an RGB color using a color transform.
CMTranslateRGBs |  | Translates bitmap colors using a color transform.
CMTranslateRGBsExt |  | Translates bitmap colors with callback progress reporting.
ColorCorrectPalette | Corrects the entries in a palette for a device context.
ColorMatchToTarget | Performs color mapping for preview purposes.
ConvertColorNameToIndex | Converts color names in a named color space to index numbers in a color profile.
ConvertIndexToColorName | Converts indices in a color space to an array of names in a named color space.
CreateColorSpace | Creates a color space.
CreateColorTransform | Creates a color transform.
CreateDeviceLinkProfile | Creates an ICC device-link profile.
CreateMultiProfileTransform | Creates a transform from multiple profiles.
CreateProfileFromLogColorSpace | Creates a device profile from a logical color space
DeleteColorSpace | Deletes a color space.
DeleteColorTransform | Deletes a color transform.
DisassociateColorProfileFromDevice | Disassociates a color profile from a device.
EnumColorProfiles | Enumerates color profiles satisfying specified criteria.
EnumICMProfiles | Enumerates output color profiles available for a given device context.
EnumICMProfilesProcCallback | Application-defined callback function for EnumICMProfiles.
GetCMMInfo | Identifies the CMM that created a transform.
GetColorDirectory | Identifies the system color directory.
GetColorProfileElement | Retrieves data from a given profile element.
GetColorProfileElementTag | Retrieves the tag name from a profile element.
GetColorProfileFromHandle | Retrieves the color profile contents given a handle to an open color profile.
GetColorProfileHeader | Retrieves the header from a profile.
GetColorSpace | Gets the current input color space in a device context.
GetCountColorProfileElements | Counts the tagged elements in a profile.
GetDeviceGammaRamp | Gets the gamma ramp from direct color display boards.
GetICMProfile | Gets the current output color profile of a device context.
GetLogColorSpace | Gets the LOGCOLORSPACE structure of a device context.
GetNamedProfileInfo | Gets information from a named color profile and stores it in a NAMED_PROFILE_INFO structure.
GetPS2ColorRenderingDictionary | Gets a PostScript color rendering dictionary.
GetPS2ColorRenderingIntent | Gets a PostScript color rendering intents.
GetPS2ColorSpaceArray | Gets a PostScript color space from a profile.
GetStandardColorSpaceProfile | Retrieves a registered standard space profile.
ICMProgressProcCallback | Application-supplied callback to report progress.
InstallColorProfile | Installs a color profile for use in the system.
IsColorProfileTagPresent | Checks that a given tag is present in a profile.
IsColorProfileValid | Checks that a profile is a valid ICC profile.
OpenColorProfile | Opens a profile and returns a handle to it.
RegisterCMM | Registers a CMM for use by the system.
SelectCMM | Specifies a preferred CMM to use.
SetColorProfileElement | Writes data for a given profile element.
SetColorProfileElementReference | Creates a tag that refers to existing tag data.
SetColorProfileElementSize | Sets the size of a given profile element.
SetColorProfileHeader | Sets the header information in a given profile.
SetColorSpace | Sets a device context's input color space.
SetDeviceGammaRamp | Sets the gamma ramp on direct color display boards.
SetICMMode | Turns color management on or off in a device context.
SetICMProfile | Sets the output color profile for a given device context.
SetStandardColorSpaceProfile | Registers a profile for a standard color space.
SetupColorMatching | Provides user control over color management by way of a dialog box.
TranslateBitmapBits | Converts bitmap colors using a color transform.
TranslateColors | Converts colors using a color transform.
UninstallColorProfile | Uninstalls a color profile from the system.
UnregisterCMM | Removes the CMM registration.


ApplyCallbackFunction

The function ApplyCallbackFunction is a callback function which updates the ICM configuration data while the dialog box displayed by the SetupColorMatching function is executing. The name ApplyCallbackFunction is a placeholder. The actual name of this callback function is supplied by the application using ICM.

BOOL ApplyCallbackFunction(
  COLORMATCHSETUP *pColorMatchSetup,
  LPARAM lParam
);

Parameters

pColorMatchSetup
Pointer to a COLORMATCHSETUP structure that contains ICM configuration data.
lParam
Contains a value supplied by the application.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

The ApplyCallbackFunction function is used to change the ICM configuration for a device while the Color Management dialog box is displayed. The Color Management dialog box is displayed by the SetupColorMatching function.

If the callback function is provided, an Apply button is displayed in the lower right of the dialog box. When you select the Apply button, the callback function immediately updates the configuration for the device being set up. The Color Management dialog box remains on the screen.

An application supplies a callback function to ICM by storing the address of the callback function in the COLORMATCHSETUP structure that is passed to the SetupColorMatching function. The address is stored in the lpfnApplyCallback member of the COLORMATCHSETUP structure. The dwFlags member should be set to CMS_USEAPPLYCALLBACK, or the callback function will be ignored.

A value supplied by the application may be passed to the callback function. Prior to invoking the SetupColorMatching function, the application can store a value in the lParamApplyCallback member of the COLORMATCHSETUP structure. When the callback function is invoked, the value in the lParamApplyCallback structure member will be passed to the callback function in its lParam parameter.

The callback function is completely optional. If it is not supplied, the Apply button does not appear in the Color Management dialog box.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, SetupColorMatching, COLORMATCHSETUP


AssociateColorProfileWithDevice

The AssociateColorProfileWithDevice function associates a specified color profile with a specified device.

BOOL WINAPI AssociateColorProfileWithDevice(
  PCTSTR pMachineName,  // reserved, must be NULL
  PCTSTR pProfileName,  // file name containing device profile
  PCTSTR pDeviceName    // name of device
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the machine on which to associate the specified profile and device. A NULL pointer indicates the local machine.
pProfileName
Points to the file name of the profile to associate.
pDeviceName
Points to the name of the device to associate.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

The AssociateColorProfileWithDevice function will fail if the profile has not been installed on the computer using the InstallColorProfile function.

Note that under Windows (Windows 95 or later), the PostScript device driver for printers assumes a CMYK color model. Therefore, all PostScript printers must use a CMYK color profile. Windows NT does not have this limitation.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


CheckBitmapBits

The CheckBitmapBits function checks whether the pixels in a specified bitmap lie within the output gamut of a specified transform.

BOOL WINAPI CheckBitmapBits(
  HTRANSFORM hColorTransform,
  PVOID pSrcBits,
  BMFORMAT bmInput,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwStride,
  PBYTE paResult,
  PBMCALLBACKFN pfnCallback,
  LPARAM lpCallbackData
);

Parameters

hColorTransform
Handle to the color transform to use.
pSrcBits
Pointer to the bitmap to check against the output gamut.
bmInput
Specifies the format of the bitmap. Must be set to one of the values of the BMFORMAT enumerated type.
dwWidth
Specifies the number of pixels per scan line of the bitmap.
dwHeight
Specifies the number of scan lines of the bitmap.
dwStride
Specifies the number of bytes from the beginning one scan line to the beginning of the next one. If set to zero, the bitmap scan lines are assumed to be padded so as to be DWORD-aligned.
paResult
Pointer to an array of bytes where the test results are to be placed. This results buffer must contain at least as many bytes as there are pixels in the bitmap.
pfnCallback
Pointer to a callback function called periodically by CheckBitmapBits to report progress and allow the calling process to cancel the bitmap test. (See ICMProgressProcCallback)
lpCallbackData
Data passed back to the callback function, for example, to identify the bitmap test about which progress is being reported.

Return Values

If this function succeeds, the return value is a nonzero value.

If this function fails, the return value is zero. For extended error information, call GetLastError.

Remarks

If the input format is not compatible with the color transform, the CheckBitmapBits function fails.

This function places results of the tests in the buffer pointed to by paResult. Each byte in the buffer corresponds to a pixel in the bitmap, and has an unsigned value between 0 and 255. The value 0 denotes that the color is in gamut, while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n + 1 indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, ICMProgressProcCallback, BMFORMAT


CheckColors

The CheckColors function determines whether the colors in an array lie within the output gamut of a specified transform.

BOOL WINAPI CheckColors(
  HTRANSFORM hColorTransform,
  PCOLOR paInputColors,
  DWORD nColors,
  COLORTYPE ctInput,
  PBYTE paResult
);

Parameters

hColorTransform
Handle to the color transform to use.
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 paResult.
ctInput
Specifies the input color type.
paResult
Pointer to an array of nColors bytes that receives the results of the test.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the input color type is not compatible with the color transform, CheckColors fails.

The function places results of the tests in the array pointed to by paResult. Each byte in the array corresponds to a COLOR element in the array pointed to by paInputColors and has an unsigned value between 0 and 255. The value 0 denotes that the color is in gamut, while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n+1 indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, The COLOR Structure


CheckColorsInGamut

The CheckColorsInGamut function determines whether a specified set of RGB triples lies in the output gamut of a specified device. The RGB triples are interpreted in the input logical color space.

BOOL WINAPI CheckColorsInGamut(
  HDC hDC,              // device context handle
  LPVOID lpRGBTriples,  // array of RGB triples
  LPVOID lpBuffer,      // buffer for results
  UINT nCount           // number of triples
);

Parameters

hDC
Handle to the device context whose output gamut to be checked.
lpRGBTriples
Pointer to an array of RGB triples to check.
lpBuffer
Pointer to the buffer in which the results are to be placed. This buffer must be at least as large as nCount bytes.
nCount
The number of elements in the array of triples.

Return Values

If this function succeeds, the return value is a nonzero value.

If this function fails, the return value is zero.

Remarks

The function places the test results in the buffer pointed to by lpBuffer. Each byte in the buffer corresponds to an RGB triple, and has an unsigned value between 0 and 255. The value 0 denotes that the color is in gamut, while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n + 1 indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n, as specified by the ICC Profile Format Specification. For more information on the ICC Profile Format Specification, see the sources listed in Other Color Management Information Sources.

Note that for this function to succeed, ICM must be enabled for the device context handle that is passed in through the hDC parameter. ICM can be enabled for a device context handle by calling the SetICMMode function.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, SetICMMode


CloseColorProfile

(Currently planned for the next releases of Windows and Windows NT)

This CloseColorProfile closes an open profile handle.

BOOL WINAPI CloseColorProfile(
  HPROFILE hProfile
);

Parameters

hProfile
Handle to the profile to be closed.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMCheckColors

The CMCheckColors function determines whether given colors lie within the output gamut of a specified transform.

BOOL WINAPI CMCheckColors(
  HCMTRANSFORM hcmTransform,  // transform handle
  LPCOLOR lpaInputColors,     // array of COLORs
  DWORD nColors,              // COLOR array size
  COLORTYPE ctInput,          // input color type
  LPBYTE lpaResult            // buffer for results
);

Parameters

hcmTransform
Handle to the color transform to use.
lpaInputColors
Pointer to an array of COLOR structures to check against the output gamut.
nColors
Specifies the number of elements in the array.
ctInput
Specifies the input color type.
lpaResult
Pointer to a buffer in which to place an array of bytes containing the test results. Each byte in the buffer corresponds to a COLOR structure, and on exit has been set to an unsigned value between 0 and 255. The value 0 denotes that the color is in gamut, while a nonzero value indicates that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n + 1 indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n. These values are usually generated from the gamutTag in the ICC profile.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. If the function is not successful, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

If the input color type is not compatible with the color transform CMCheckColors fails.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMCheckColorsInGamut

The CMCheckColorsInGamut function determines whether specified RGB triples lie in the output gamut of a specified transform.

BOOL WINAPI CMCheckColorsInGamut(
  HCMTRANSFORM hcmTransform,  // transform handle
  RGBTRIPLE *lpaRGBTriple,    // RGB triple array
  LPBYTE lpaResult,           // buffer for results
  UINT nCount                 // result buffer size
);

Parameters

hcmTransform
Specifies the transform to use.
lpaRGBTriple
Points to an array of RGB triples to check.
lpaResult
Points to the buffer in which to put results.

The results are represented by an array of bytes. Each byte in the array corresponds to an RGB triple and has an unsigned value between 0 and 255. The value 0 denotes that the color is in gamut, while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n + 1 indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n.

nCount
Specifies the number of elements in the array.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. If the function is not successful, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMCheckRGBs

The CMCheckRGBs function checks whether the pixels in a bitmap lie within the output gamut of a specified transform.

BOOL WINAPI CMCheckRGBs(
  HCMTRANSFORM hcmTransform,
  LPVOID lpSrcBits,
  BMFORMAT bmInput,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwStride,
  LPBYTE lpaResult,
  PBMCALLBACKFN pfnCallback,
  ULONG ulCallbackData
);

Parameters

hcmTransform
Specifies the color transform to use.
lpSrcBits
Points to the bitmap to check against an output gamut.
bmInput
Specifies the input bitmap format.
dwWidth
Specifies the number of pixels per scan line in the input bitmap.
dwHeight
Specifies the number of scan lines in the input bitmap.
dwStride
Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the input bitmap. If dwStride is set to zero, the CMM should assume that scan lines are padded so as to be DWORD-aligned.
lpaResult
Points to a buffer in which the test results are to be placed.

The results are represented by an array of bytes. Each byte in the array corresponds to a pixel in the bitmap, and on exit is set to an unsigned value between 0 and 255. The value 0 denotes that the color is in gamut, while a nonzero value denotes that it is out of gamut. For any integer n such that 0 < n < 255, a result value of n + 1 indicates that the corresponding color is at least as far out of gamut as would be indicated by a result value of n. These values are usually generated from the gamutTag in the ICC profile.

pfnCallback
Pointer to an application-supplied callback function called periodically by CMCheckRGBs to report progress and allow the calling process to cancel the translation. (See ICMProgressProcCallback.)
ulCallbackData
Data passed back to the callback function, for example to identify the bitmap test that is reporting progress.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. If the function is not successful, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

If the input format is not compatible with the color transform, the CMCheckRGBs function fails.

If the callback function returns 0, processing should be canceled and CMCheckRGBs should return zero to indicate failure; the results buffer may be partially filled.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, ICMProgressProcCallback


CMConvertColorNameToIndex

The CMConvertColorNameToIndex function converts color names in a named color space to index numbers in a color profile

BOOL WINAPI CMConvertColorNameToIndex(
  HPROFILE hProfile,
  PCOLOR_NAME paColorName,
  PDWORD paIndex,
  DWORD dwCount
);

Parameters

hProfile
The handle to a named color profile.
paColorName
Pointer to an array of color name structures.
paIndex
Pointer to an array of DWORDS that this function fills with the indices.
dwCount
The number of color names to convert.

Return Values

If this function succeeds with the conversion, the return value is TRUE.

If this function fails, the return value is FALSE. When this occurs, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

This function is required in the default CMM. It is optional for all other CMMs.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMConvertIndexToColorName

The CMConvertIndexToColorName transforms indices in a color space to an array of names in a named color space.

BOOL WINAPI CMConvertIndexToColorName(
  HPROFILE hProfile,
  PDWORD paIndex,
  PCOLOR_NAME paColorName,
  DWORD dwCount
);

Parameters

hProfile
The handle to a color space profile.
paIndex
Pointer to an array of color-space index numbers.
paColorName
Pointer to an array of color name structures.
dwCount
The number of indices to convert.

Return Values

If this conversion function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. When this occurs, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

This function is required in the default CMM. It is optional for all other CMMs.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMCreateDeviceLinkProfile

The CMCreateDeviceLinkProfile function creates a device link profile in the format specified by the International Color Consortium in its ICC Profile Format Specification.

BOOL WINAPI CMCreateDeviceLinkProfile(
  LPHPROFILE lpahProfiles,  // array of profiles
  DWORD nProfiles,          // profile array size
  LPBYTE *lpProfileData     // pointer to pointer to buffer
);

Parameters

lpahProfiles
Pointer to an array of profile handles.
nProfiles
Specifies the number of profiles in the array.
lpProfileData
Pointer to a pointer to a buffer. If successful the function allocates and fills this buffer. The calling application must free this buffer when it is no longer needed. Use the GlobalFree function to free this buffer.

Return Values

If the function succeeds, the return value is a nonzero value.

If this function fails, the return value is zero. If the function is not successful, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Only the Windows default CMM is required to export this function; it is optional for all other CMMs.

If a CMM does not support CMCreateDeviceLinkProfile, Windows uses the default CMM to create a device link profile.

The first and the last profiles in the array must be device profiles. The other profiles can be color space or abstract profiles. Each profile's output color space must be the next profile's input color space.

The calling application must free the buffer allocated by this function and pointed to by the lpProfileData parameter. Use the GlobalFree function to free the buffer.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, GlobalFree


CMCreateMultiProfileTransform

The CMCreateMultiProfileTransform function accepts an array of profiles or a single device link profile and creates a color transform. This transform is a mapping from the color space specified by the first profile to that of the second profile and so on to the last one.

HCMTRANSFORM CMCreateMultiProfileTransform(
  LPHPROFILE lpahProfiles,  // array of profile handles
  DWORD nProfiles,          // profile handle array size
  PDWORD padwIntents,       // array of rendering intents
  DWORD nIntents,           // intent array size
  DWORD dwFlags             // transform creation flags
);

Parameters

lpahProfiles
Points to an array of profile handles.
nProfiles
Specifies the number of profiles in the array.
padwIntents
Points to an array of rendering intents. Each rendering intent is represented by one of the following values:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

nIntents
Specifies the number of intents in the intent array. Can be 1, or the same value as nProfiles.
dwFlags
Specifies flags to used control creation of the transform. These flags are intended only as hints, and it is up to the CMM to determine how best to use these flags.

Set the high-order WORD to ENABLE_GAMUT_CHECKING if the transform will be used for gamut checking.

The low-order WORD can have one of the following constant values: PROOF_MODE, NORMAL_MODE, BEST_MODE. Moving from PROOF_MODE to BEST_MODE, output quality generally improves and transform speed declines.

Return Values

If this function succeeds, the return value is a color transform in the range 256 to 65,535. Since only the low WORD of the transform is retained, valid transforms cannot exceed this range.

If this function fails, the return value is an error code having a value less than 256. When the return value is less than 256, signaling an error, the CMM should use SetLastError to set the last error to a valid error value as defined in Winerror.h.

Remarks

Every CMM is required to export this function.

The array of intents specifies how profiles should be combined. The nth intent is used for combining the nth profile in the array. If only one intent is specified, it is used for the first profile, and all other profiles are combined using Absolute Colorimetric intent.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMCreateProfile

The CMCreateProfile ANSI function creates a display color profile from a LOGCOLORSPACE structure.

BOOL WINAPI CMCreateProfile(
  LPLOGCOLORSPACEA lpColorSpace,  // pointer to a color space
  LPBYTE *lpProfileData           // pointer to pointer to buffer
);

Parameters

lpColorSpace
Pointer to a color logical space, of which the lcsFilename member will be NULL.
lpProfileData
Pointer to a pointer to a buffer. If successful the function allocates and fills this buffer. It is the calling application's responsibility to free this buffer when it is no longer needed.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. If the function is not successful, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

The Unicode version of this function is CMCreateProfileW.

Only the Windows default CMM is required to export this function; it is optional for all other CMMs.

If a CMM does not support CMCreateProfile, Windows uses the default CMM to create the profile.

The CMM should set all header fields to sensible defaults. This profile should be usable as the input profile in a transform.

The calling application must free the buffer allocated by this function and pointed to by the lpProfileData parameter. Use GlobalFree to free the buffer.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, CMCreateProfileW


CMCreateProfileW

The CMCreateProfileW Unicode function creates a display color profile from a LOGCOLORSPACE structure.

BOOL WINAPI CMCreateProfileW(
  LPLOGCOLORSPACEW lpColorSpace,  // pointer to a color space
  LPBYTE *lpProfileData           // pointer to pointer to buffer
);

Parameters

lpColorSpace
Points to a logical color space, of which the lcsFilename member will be NULL.
lpProfileData
Points to a pointer to a buffer. If successful the function allocates and fills this buffer. The calling application must free this buffer when it is no longer needed. Use the GlobalFree function to free this buffer.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. If the function is not successful, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

The ANSI version of this function is CMCreateProfile.

Only the Windows default CMM is required to export this function; it is optional for all other CMMs. If a CMM does not support CMCreateProfileW, Windows uses the default CMM to create the profile.

The CMM should set all header fields to sensible defaults. This profile should be usable as the input profile in a transform.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, CMCreateProfile, GlobalFree


CMCreateTransform

The CMCreateTransform ANSI function creates a color transform that maps from an input LOGCOLORSPACE to an optional target space and then to an output device.

HCMTRANSFORM WINAPI CMCreateTransform(
  LPLOGCOLORSPACEA lpColorSpace,       // color space pointer
  LPDEVCHARACTER lpDevCharacter,       // profile file name
  LPDEVCHARACTER lpTargetDevCharacter  // target profile file name
);

Parameters

lpColorSpace
Pointer to an input logical color space structure.
lpDevCharacter
Pointer to a memory-mapped device profile. For 16-bit device drivers that are ICM aware, lpDevCharacter points to the profile file name.
lpTargetDevCharacter
Points to a memory-mapped target profile.

Return Values

If this function succeeds, the return value is a color transform in the range 256 to 65,535. Since only the low WORD of the transform is retained, valid transforms cannot exceed this range.

If this function fails, the return value is an error code having a value less than 256. When the return value is less than 256, signaling an error, the CMM should use SetLastError to set the last error to a valid error value as defined in Winerror.h.

Remarks

The Unicode equivalent of the CMCreateTransform function is CMCreateTransformW.

Every CMM is required to export this function.

The forward transform must be already computed before calling CMCreateTransform. Future calls to the translate functions (CMTranslateColors, CMTranslateRGB, CMTranslateRGBs, and CMTranslateRGBsExt) using the forward transform should not fail due to inability to construct the mapping.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, CMCreateTransformW, CMTranslateColors, CMTranslateRGB, CMTranslateRGBs, CMTranslateRGBsExt


CMCreateTransformExt

The CMCreateTransformExt ANSI function creates a color transform that maps from an input LOGCOLORSPACE to an optional target space and then to an output device, using a set of flags that define how the transform should be created.

HCMTRANSFORM WINAPI CMCreateTransformExt(
  LPLOGCOLORSPACEA lpColorSpace,        // color space pointer
  LPDEVCHARACTER lpDevCharacter,        // profile file name
  LPDEVCHARACTER lpTargetDevCharacter,  // target profile file name
  DWORD dwFlags                         // creation flags
);

Parameters

lpColorSpace
Pointer to an input logical color space structure.
lpDevCharacter
Pointer to a memory-mapped device profile.
lpTargetDevCharacter
Pointer to a memory-mapped target profile.
dwFlags
Specifies flags to control creation of the transform. It is up to the CMM to determine how best to use these flags.

Set the high-order WORD to ENABLE_GAMUT_CHECKING if the transform will be used for gamut checking.

The low-order WORD can have one of the following constant values: PROOF_MODE, NORMAL_MODE, BEST_MODE. Moving from PROOF_MODE to BEST_MODE, output quality generally improves and transform speed declines.

Return Values

If this function succeeds, the return value is a color transform in the range 256 to 65,535. Since only the low WORD of the transform is retained, valid transforms cannot exceed this range.

If this function fails, the return value is an error code having a value less than 256. When the return value is less than 256, signaling an error, the CMM should use SetLastError to set the last error to a valid error value as defined in Winerror.h.

Remarks

The Unicode equivalent of CMCreateTransformExt is CMCreateTransformExtW.

Every CMM is required to export this function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, CMCreateTransformExtW


CMCreateTransformExtW

The CMCreateTransformExtW Unicode function creates a color transform that maps from an input LOGCOLORSPACE to an optional target space and then to an output device. A set of flags defines how the transform should be created.

HCMTRANSFORM WINAPI CMCreateTransformExtW(
  LPLOGCOLORSPACEW lpColorSpace,        // color space pointer
  LPDEVCHARACTER lpDevCharacter,        // profile file name
  LPDEVCHARACTER lpTargetDevCharacter,  // target profile file name
  DWORD dwFlags                         // creation flags
);

Parameters

lpColorSpace
Pointer to an input logical color space structure.
lpDevCharacter
Pointer to a memory-mapped device profile.
lpTargetDevCharacter
Points to a memory-mapped target profile.
dwFlags
Specifies flags to control creation of the transform. These flags are intended only as hints, and it is up to the CMM to determine how best to use these flags.

Set the high-order WORD to ENABLE_GAMUT_CHECKING if the transform will be used for gamut checking.

The low-order WORD can have one of the following constant values: PROOF_MODE, NORMAL_MODE, BEST_MODE. Moving from PROOF_MODE to BEST_MODE, output quality generally improves and transform speed declines.

Return Values

If this function succeeds, the return value is a color transform in the range 256 to 65,535. Since only the low WORD of the transform is retained, valid transforms cannot exceed this range.

If this function fails, the return value is an error code having a value less than 256. When the return value is less than 256, signaling an error, the CMM should use SetLastError to set the last error to a valid error value as defined in Winerror.h.

Remarks

The ANSI equivalent of CMCreateTransformExtW is CMCreateTransformExt.

Every CMM is required to export this function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, CMCreateTransformExt, LOGCOLORSPACE


CMCreateTransformW

The CMCreateTransformW Unicode function creates a color transform that maps from an input LOGCOLORSPACE to an optional target space and then to an output device.

HCMTRANSFORM WINAPI CMCreateTransformW(
  LPLOGCOLORSPACEW lpColorSpace,       // color space pointer
  LPDEVCHARACTER lpDevCharacter,       // profile file name
  LPDEVCHARACTER lpTargetDevCharacter  // target profile file name
);

Parameters

lpColorSpace
Pointer to an input logical color space structure. If the lcsFilename member of the COLORSPACEW structure is nonzero, lpColorSpace is a pointer to the memory-mapped profile.
lpDevCharacter
Pointer to a memory-mapped device profile.
lpTargetDevCharacter
Pointer to a memory-mapped target profile.

Return Values

If this function succeeds, the return value is a color transform in the range 256 to 65,535. Since only the low WORD of the transform is retained, valid transforms cannot exceed this range.

If this function fails, the return value is an error code having a value less than 256. When the return value is less than 256, signaling an error, the CMM should use SetLastError to set the last error to a valid error value as defined in Winerror.h.

Remarks

The ANSI equivalent of CMCreateTransformW is CMCreateTransform.

Every CMM is required to export the CMCreateTransformW function. The forward transform must be already computed when calling this function. Future calls to translate functions (CMTranslateColors, CMTranslateRGB, CMTranslateRGBs, and CMTranslateRGBsExt) using the forward transform should not fail due to inability to construct the mapping.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, CMCreateTransform, CMTranslateColors, CMTranslateRGB, CMTranslateRGBs, CMTranslateRGBsExt


CMDeleteTransform

The CMDeleteTransform function deletes a specified color transform, and frees any memory associated with it.

BOOL WINAPI CMDeleteTransform(
  HCMTRANSFORM hcmTransform
);

Parameters

hcmTransform
Identifies the color transform to be deleted.

Return Values

If this function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. If the CMDeleteTransform function is not successful, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMGetInfo

The CMGetInfo function retrieves various information about the color management module (CMM).

Every CMM is required to export this function.

DWORD WINAPI CMGetInfo(
  DWORD dwInfo
);

Parameters

dwInfo
Specifies what information should be retrieved. This parameter can take one of the following constant values:
Constant | Significance of the function's return value
CMM_DESCRIPTION | A text string that describes the color management module.
CMM_DLL_VERSION | Version number of the CMM DLL.
CMM_DRIVER_LEVEL | Driver compatibility information.
CMM_IDENT | The CMM identification signature registered with the International Color Consortium (ICC).
CMM_LOGOICON | The logo icon for this CMM.
CMM_VERSION | Version of Windows supported.
CMM_WIN_VERSION | Backward compatibility with Windows 95.

Return Values

If this function succeeds, the return value is a nonzero value whose significance depends on the dwInfo parameter:

dwInfo | CMGetInfo returns
CMM_DESCRIPTION | The resource ID of a string containing a text description of the CMM.
CMM_DLL_VERSION | Version number of the CMM DLL
CMM_DRIVER_LEVEL | CMS_LEVEL_1 (for compatibility ICM 1.0)
CMM_IDENT | ICC registered signature of the CMM DLL
CMM_LOGOICON | The logo icon resource ID.
CMM_VERSION | 0x00050000
CMM_WIN_VERSION | 0x00040000 (for compatibility ICM 1.0)

If the function fails, the return value is zero.

Remarks

CMMs that do not run on Windows 95 should return 0x0050000 for CMM_WIN_VERSION.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMGetNamedProfileInfo

The CMGetNamedProfileInfo function retrieves information about the specified named color profile.

BOOL WINAPI CMGetNamedProfileInfo(
  HPROFILE hProfile,
  PNAMED_PROFILE_INFO pNamedProfileInfo
);

Parameters

hProfile
The handle to the profile from which the information will be retrieved.
pNamedProfileInfo
A pointer to a NAMED_PROFILE_INFO structure.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. When this occurs, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

This function is required in the default CMM. It is optional for all other CMMs.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, NAMED_PROFILE_INFO


CMGetPS2ColorRenderingDictionary

The CMGetPS2ColorRenderingDictionary function retrieves the PostScript Level 2 color rendering dictionary for a given rendering intent from a given profile.

BOOL WINAPI CMGetPS2ColorRenderingDictionary(
  HPROFILE hProfile,
  DWORD dwIntent,
  LPBYTE lpBuffer,
  LPDWORD lpcbSize,
  LPBOOL lpbBinary
);

Parameters

hProfile
Specifies the profile to use.
dwIntent
Specifies the rendering intent. Can be one of the following values:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

lpBuffer
Pointer to a buffer in which the color rendering dictionary is to be placed. If the pointer is NULL, the function returns the size required for this buffer in the memory location pointed to by lpcbSize.
lpcbSize
Pointer to a variable specifying the size of the buffer. On return, the variable contains the number of bytes actually copied to the buffer.
lpbBinary
Points to a Boolean variable. If its value is TRUE, data returned could be binary, or if FALSE, the data should be ASCII85 encoded. On return, the value pointed to by lpbBinary indicates whether the data returned actually is binary or ASCII85.

Return Values

If this function succeeds, the return value is TRUE. It also returns TRUE if it is called with lpBuffer set to NULL and the size of the required buffer is copied into lpcbSize.

If this function fails, the return value is FALSE. When this occurs, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

This function is optional for all CMMs.

If a CMM does not support this function, Windows uses the default CMM to create the color rendering dictionary.

If the color rendering dictionary tag is not present in the profile indicated by hProfile, the CMM creates the color rendering dictionary from the profile contents. The resulting color rendering dictionary can be used as the operand for the PostScript Level 2 setcolorrendering operator.

This function fails if the profile indicated by hProfile does not have LUT tags associated with it. For more information on LUT tags, see the ICC Profile Format Specification available at www.color.org.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMGetPS2ColorRenderingIntent

The CMGetPS2ColorRenderingIntent function retrieves the PostScript Level 2 color rendering intent from a profile.

BOOL WINAPI CMGetPS2ColorRenderingIntent(
  HPROFILE hProfile,
  DWORD dwIntent,
  LPBYTE lpBuffer,
  LPDWORD lpcbSize
);

Parameters

hProfile
Specifies the profile to use.
dwIntent
Specifies the desired rendering intent to retrieve. Can be one of the following values:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

lpBuffer
Points to a buffer in which the color rendering intent is to be placed. If the pointer is NULL, the function returns the size required for this buffer in *lpcbSize.
lpcbSize
Points to a variable specifying the size of the buffer. On return, the variable contains has the number of bytes actually copied to the buffer.

Return Values

If this function succeeds, the return value is TRUE. It also returns TRUE if it is called with lpBuffer set to NULL and the size of the required buffer is copied into lpcbSize.

If this function fails, the return value is FALSE. When this occurs, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

This function is optional for all CMMs.

If a CMM does not support this function, Windows uses the default CMM to get the color rendering intent.

If the tag is not present in the profile indicated by hProfile, the CMM creates it. The resulting rendering intent can be used as the operand for the PostScript Level 2 findcolorrendering operator.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMGetPS2ColorSpaceArray

The CMGetPS2ColorSpaceArray function retrieves the PostScript Level 2 color space array from a profile.

BOOL WINAPI CMGetPS2ColorSpaceArray(
  HPROFILE hProfile,
  DWORD dwIntent,
  DWORD dwCSAType,
  LPBYTE lpBuffer,
  LPDWORD lpcbSize,
  LPBOOL lpbBinary
);

Parameters

hProfile
Specifies the profile to use.
dwIntent
Specifies the desired rendering intent for the color space array. Can be one of the following values:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

dwCSAType
Specifies the type of color space array. Can take one of the following values:
Constant | Meaning
CSA_A | Get a CIEBasedA color space array from the monochrome profile.
CSA_GRAY | Get a CIEBasedA color space array from the monochrome profile.
CSA_ABC | Get a CIEBasedABC color space array from the RGB or L*a*b profile.
CSA_DEF | Get a CIEBasedDEF color space array from the RGB or L*a*b profile.
CSA_RGB | Get a CIEBasedDEF color space array followed by a CIEBasedABC color space array from the RGB profile. On execution, if the printer doesn't support CIEBasedDEF color spaces, the function uses the CIEBasedABC definition.
CSA_Lab | Gets a CIEBasedABC color space array from the L*a*b profile.
CSA_DEFG | Get a CIEBasedDEFG color space array from the CMYK profile.
CSA_CMYK | Get a CIEBasedCMYK color space array from the CMYK profile.

lpBuffer
Pointer to a buffer in which the color space array is to be placed. If the pointer is NULL, the function returns the size required for this buffer in the memory location pointed to by lpcbSize.
lpcbSize
Pointer to a variable specifying the size of the buffer. On return, the variable contains has the number of bytes actually copied to the buffer.
lpbBinary
Pointer to a Boolean variable. If its value is TRUE, data returned could be binary, or if FALSE, the data should be ASCII85 encoded. On return, the value of in the memory location pointed to by lpbBinary indicates whether the data returned actually is binary or ASCII85.

Return Values

If this function succeeds, the return value is TRUE. It also returns TRUE if it is called with lpBuffer set to NULL and the size of the required buffer is copied into lpcbSize.

If this function fails, the return value is FALSE. When this occurs, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

This function is optional for all CMMs.

If a CMM does not support this function, Windows uses the default CMM to create the color space array.

If the color space array tag is not present in the profile, the CMM should create the color space array from the profile contents. The resulting color space array can be used as the operand for the PostScript Level 2 setcolorspace operator.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMIsProfileValid

The CMIsProfileValid function reports whether the given profile is a valid ICC profile that can be used for color management.

BOOL WINAPI CMIsProfileValid(
  HPROFILE hProfile,
  LPBOOL lpbValid
);

Parameters

hProfile
Specifies the profile to check.
lpbValid
Pointer to a variable that is set on exit to TRUE if the profile is a valid ICC profile, or FALSE if not.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. If the function fails, the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Only the Windows default CMM is required to export this function; it is optional for all other CMMs.

If a CMM does not support this function, Windows uses the default CMM to validate the profile.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMTranslateColors

The CMTranslateColors function translates an array of colors from a source color space to a destination color space using a color transform.

BOOL WINAPI CMTranslateColors(
  HCMTRANSFORM hcmTransform,
  LPCOLOR lpaInputColors,
  DWORD nColors,
  COLORTYPE ctInput,
  LPCOLOR lpaOutputColors,
  COLORTYPE ctOutput
);

Parameters

hcmTransform
Specifies the color transform to use.
lpaInputColors
Points to an array of COLOR structures to translate.
nColors
Specifies the number of elements in the array.
ctInput
Specifies the color type of the input.
lpaOutputColors
Points to a buffer in which an array of translated COLOR structures is to be placed.
ctOutput
Specifies the output color type.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. The CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

If the input and the output color types are not compatible with the color transform, this function should fail.

Note that this function must support in-place translation. That is, whenever the memory footprint of the output is less than or equal to the memory footprint of the input, this function must be able to translate the bitmap colors even if the source and destination buffers are the same.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMTranslateRGB

The CMTranslateRGB function translates an application-supplied RGBQuad into the device color space.

BOOL WINAPI CMTranslateRGB(
  HCMTRANSFORM hcmTransform,
  COLORREF ColorRef,
  LPCOLORREF lpColorRef,
  DWORD dwFlags
);

Parameters

hcmTransform
Specifies the transform to be used.
ColorRef
The RGBQuad to translate.
lpColorRef
Points to a buffer in which to place the translation.
dwFlags
Specifies how the transform should be used to make the translation. This parameter can take one of the following meanings:
Value | Meaning
CMS_FORWARD | Use forward transform
CMS_BACKWARD | Use reverse transform

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. The CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMTranslateRGBs

The CMTranslateRGBs function translates a bitmap from one color space to another using a color transform.

BOOL WINAPI CMTranslateRGBs(
  HCMTRANSFORM hcmTransform,
  LPVOID lpSrcBits,
  BMFORMAT bmInput,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwStride,
  LPVOID lpDestBits,
  BMFORMAT bmOutput,
  DWORD dwTranslateDirection
);

Parameters

hcmTransform
Specifies the color transform to use.
lpSrcBits
Points to the bitmap to translate.
bmInput
Specifies the input bitmap format.
dwWidth
Specifies the number of pixels per scan line in the input bitmap.
dwHeight
Specifies the number of scan lines in the input bitmap.
dwStride
Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the input bitmap. If dwStride is set to zero, the CMM should assume that scan lines are padded so as to be DWORD-aligned.
lpDestBits
Points to a destination buffer in which to place the translated bitmap.
bmOutput
Specifies the output bitmap format.
dwTranslateDirection
Specifies the direction of the transform being used for the translation. This parameter must take one of the following values:
Value | Meaning
CMS_FORWARD | Use forward transform
CMS_BACKWARD | Use reverse transform

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE and the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

When writing into the destination buffer, the CMM should make sure that scan lines are padded to be DWORD-aligned.

If the input and output formats are not compatible with the color transform, this function fails.

If both input and output bitmap formats are 3 channel, 4 bytes per pixel as in the case of BM_xRGBQUADS, the 4th bytes should be preserved and copied to the output buffer.

Note that this function must support in-place translation. That is, whenever the memory footprint of the output is less than or equal to the memory footprint of the input, this function must be able to translate the bitmap colors even if the source and destination buffers are the same.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CMTranslateRGBsExt

The CMTranslateRGBsExt function translates a bitmap from one defined format into a different defined format and calls a callback function periodically, if one is specified, to report progress and permit the calling application to terminate the translation.

BOOL WINAPI CMTranslateRGBsExt(
  HCMTRANSFORM hcmTransform,
  LPVOID lpSrcBits,
  BMFORMAT bmInput,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwInputStride,
  LPVOID lpDestBits,
  BMFORMAT bmOutput,
  DWORD dwOutputStride,
  LPBMCALLBACKFN lpfnCallback,
  ULONG ulCallbackData
);

Parameters

hcmTransform
Specifies the color transform to use.
lpSrcBits
Pointer to the bitmap to translate.
bmInput
Specifies the input bitmap format.
dwWidth
Specifies the number of pixels per scan line in the input bitmap.
dwHeight
Specifies the number of scan lines in the input bitmap.
dwInputStride
Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the input bitmap. If dwInputStride is set to zero, the CMM should assume that scan lines are padded so as to be DWORD-aligned.
lpDestBits
Points to a destination buffer in which to place the translated bitmap.
bmOutput
Specifies the output bitmap format.
dwOutputStride
Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the input bitmap. If dwOutputStride is set to zero, the CMM should pad scan lines so that they are DWORD-aligned.
lpfnCallback
Pointer to an application-supplied callback function called periodically by CMTranslateRGBsExt to report progress and allow the calling process to cancel the translation. (See ICMProgressProcCallback.)
ulCallbackData
Data passed back to the callback function, for example to identify the translation that is reporting progress.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE and the CMM should call SetLastError to set the last error to a valid error value defined in Winerror.h.

Remarks

Every CMM is required to export this function.

When writing into the destination buffer, the CMM should make sure that scan lines are padded to be DWORD-aligned.

If the input and output formats are not compatible with the color transform, this function fails.

If both input and output bitmap formats are 3 channel, 4 bytes per pixel as in the case of BM_xRGBQUADS, the fourth bytes should be preserved and copied to the output buffer.

If the callback function returns zero, processing should be cancelled and CMTranslateRGBsExt should return zero to indicate failure; the output buffer may be partially filled.

Note that this function must support in-place translation. That is, whenever the memory footprint of the output is less than or equal to the memory footprint of the input, this function must be able to translate the bitmap colors even if the source and destination buffers are the same.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, ICMProgressProcCallback, Windows Bitmap Header Structures


ColorCorrectPalette

The ColorCorrectPalette function corrects the entries of a palette using the ICM 2.0 parameters in the specified device context..

BOOL WINAPI ColorCorrectPalette(
  HDC hDC,
  HPALETTE hPalette,
  DWORD dwFirstEntry,
  DWORD dwNumOfEntries
);

Parameters

hDC
Specifies a device context whose ICM parameters to use.
hPalette
Specifies the handle to the palette to be color corrected.
dwFirstEntry
Specifies the first entry in the palette to be color corrected.
dwNumOfEntries
Specifies the number of entries to color correct.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


ColorMatchToTarget

The ColorMatchToTarget function enables you to preview colors as they would appear on the target device.

BOOL WINAPI ColorMatchToTarget(
  HDC hDC,
  HDC hdcTarget,
  DWORD uiAction
);

Parameters

hDC
Specifies the device context for previewing, generally the screen.
hdcTarget
Specifies the target device context, generally a printer.
uiAction
A constant that can have one of the following values.
Constant | Meaning
CS_ENABLE | Map the colors to the target device's color gamut. This enables color proofing. All subsequent draw commands to the DC will render colors as they would appear on the target device.
CS_DISABLE | Disable color proofing.
CS_DELETE_TRANSFORM | If color management is enabled for the target profile, disable it and delete the concatenated transform.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

Remarks

ColorMatchToTarget can be used to proof the colors of a color output device on another color output device. Setting the uiAction parameter to CS_ENABLE causes all subsequent drawing commands to the DC to render colors as they would appear on the target device. If uiAction is set to CS_DISABLE, proofing is turned off.

When ColorMatchToTarget is called, the color transform for the target device is performed first, and then the transform to the preview device is applied to the results of the first transform. This is used primarily for checking gamut mapping conditions. Before using this function, you must enable ICM for both device contexts.

This function cannot be cascaded. While color mapping to the target is enabled by setting uiAction to CS_ENABLE, application changes to the color space or gamut mapping method are ignored. Those changes then take effect when color mapping to the target is disabled.

Note A memory leak will not occur if an application does not delete a transform using CS_DELETE_TRANSFORM. The transform will be deleted when either the device context (DC) is closed, or when the application color space is deleted. However if the transform is not going to be used again, or if the application will not be performing any more color matching on the DC, it should explicitly delete the transform to free the memory it occupies.

The uiAction parameter should only be set to CS_DELETE_TRANSFORM if color management is enabled before the ColorMatchToTarget function is called.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


ConvertColorNameToIndex

The ConvertColorNameToIndex function converts color names in a named color space to index numbers in a color profile

BOOL WINAPI ConvertColorNameToIndex(
  HPROFILE hProfile,
  PCOLOR_NAME paColorName,
  PDWORD paIndex,
  DWORD dwCount
);

Parameters

hProfile
The handle to a named color profile.
paColorName
Pointer to an array of color name structures.
paIndex
Pointer to an array of DWORDS that this function fills with the indices.
dwCount
The number of color names to convert.

Return Values

If this function succeeds with the conversion, the return value is TRUE.

If the conversion function fails, the return value is FALSE.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


ConvertIndexToColorName

The ConvertIndexToColorName transforms indices in a color space to an array of names in a named color space.

BOOL WINAPI ConvertIndexToColorName(
  HPROFILE hProfile,
  PDWORD paIndex,
  PCOLOR_NAME paColorName,
  DWORD dwCount
);

Parameters

hProfile
The handle to a color space profile.
paIndex
Pointer to an array of color-space index numbers.
paColorName
Pointer to an array of color name structures.
dwCount
The number of indices to convert.

Return Values

If this conversion function succeeds, the return value is TRUE.

If this conversion function fails, the return value is FALSE.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


CreateColorSpace

The CreateColorSpace function creates a logical color space.

HCOLORSPACE WINAPI CreateColorSpace(
  LPLOGCOLORSPACE lpLogColorSpace
);

Parameters

lpLogColorSpace
Pointer to the LOGCOLORSPACE data structure.

Return Values

If this function succeeds, the return value is a handle that identifies a color space.

If this function fails, the return value is NULL.

Remarks

When the color space is no longer needed, use DeleteColorSpace to delete it.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, DeleteColorSpace


CreateColorTransform

The CreateColorTransform function creates a color transform that applications can use to perform color management.

HTRANSFORM WINAPI CreateColorTransform(
  LPLOGCOLORSPACE pLogColorSpace,
  HPROFILE hDestProfile,
  HPROFILE hTargetProfile,
  DWORD dwFlags
);

Parameters

pLogColorSpace
Pointer to the input LOGCOLORSPACE.
hDestProfile
Handle to the profile of the destination device.
hTargetProfile
Handle to the profile of the target device.
dwFlags
The high-order WORD of dwFlags should be set to ENABLE_GAMUT_CHECKING if this transform will be used for gamut checking.

The low-order WORD can have one of the following constant values: PROOF_MODE, NORMAL_MODE, BEST_MODE. Moving from PROOF_MODE to BEST_MODE, output quality generally improves and transform speed declines.

Return Values

If this function succeeds, the return value is a handle to the color transform.

If this function fails, the return value is NULL. For extended error information, call GetLastError.

Remarks

If the target profile is NULL, the transform goes from the source logical color space to the destination profile. If the target profile is given, the transform goes from the source logical color space to the target profile and then to the destination profile. This allows previewing output meant for the target device on the destination device.

The values in dwFlags are intended as hints only. The color management module must determine the best way to use them.

The CreateColorTransform function is used outside of a DC. Colors may shift when transforming from a color profile to the same color profile. This is due to precision errors. Therefore, a color transform should not be performed under these circumstances.

The B2Ax tags are required for any profile that is the target of a transform.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


CreateDeviceLinkProfile

The CreateDeviceLinkProfile function creates a device link profile from a set of color profiles, using the specified intents.

BOOL WINAPI CreateDeviceLinkProfile(
  PHPROFILE pahProfiles,
  DWORD nProfiles,
  PDWORD padwIntent,
  DWORD nIntents,
  DWORD dwFlags,
  PBYTE *pProfileData,
  DWORD indexPreferredCMM
);

Parameters

pahProfiles
Pointer to an array of handles of the color profiles to be used.
nProfiles
Specifies the number of profiles in the array pointed to by pahProfiles.
padwIntent
Pointer to an array of DWORDS containing the intents to be used. See Rendering Intents.
nIntents
The number of intents in the array pointed to by padwIntent.
dwFlags
Specifies flags to control creation of the transform. It is up to the CMM to determine how best to use these flags.

Set the high-order WORD to ENABLE_GAMUT_CHECKING if the transform will be used for gamut checking.

The low-order WORD can have one of the following constant values: PROOF_MODE, NORMAL_MODE, BEST_MODE. Moving from PROOF_MODE to BEST_MODE, output quality generally improves and transform speed declines.

pProfileData
Pointer to a pointer to a buffer. If successful, this function allocates the buffer, places its address in *pProfileData, and fills it with a device link profile. If the function succeeds, the calling application must free the buffer after it is no longer needed.
indexPreferredCMM
Specifies the one-based index of the color profile that indicates which color management module (CMM) to use. If the application developer doesn't care which CMM is used and would like Windows to choose a CMM, it should set this parameter to INDEX_DONT_CARE.

Return Values

If this function succeeds, the return value is a nonzero value.

If this function fails, the return value is zero. For extended error information, call GetLastError.

Remarks

The first and the last profiles in the array must be device profiles. The other profiles can be color space or abstract profiles.

Each profile's output color space must be the next profile's input color space.

The calling application must free the buffer allocated by this function and pointed to by the pProfileData parameter. The GlobalFree function should be used to free the buffer.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, GlobalFree


CreateMultiProfileTransform

The CreateMultiProfileTransform function accepts an array of profiles or a single device link profile and creates a color transform that applications can use to perform color mapping.

HTRANSFORM WINAPI CreateMultiProfileTransform(
  PHPROFILE pahProfiles,
  DWORD nProfiles,
  PDWORD padwIntent,
  DWORD nIntents,
  DWORD dwFlags,
  DWORD indexPreferredCMM
);

Parameters

pahProfiles
Pointer to an array of handles to the profiles to be used.
nProfiles
Specifies the number of profiles in the array.
padwIntent
Pointer to an array of intents to use. Each intent is one of the following values:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

nIntents
Specifies the number of elements in the intents array: can either be 1 or the same value as nProfiles.
dwFlags
The high-order WORD of dwFlags should be set to ENABLE_GAMUT_CHECKING if this transform will be used for gamut checking.

The low-order WORD can have one of the following constant values: PROOF_MODE, NORMAL_MODE, BEST_MODE. Moving from PROOF_MODE to BEST_MODE, output quality generally improves and transform speed declines.

indexPreferredCMM
One-based index of the profile that specifies the color management module (CMM) to use. If indexPreferredCMM is set to INDEX_DONT_CARE, the CMM will be selected automatically.

Return Values

If this function succeeds, the return value is a handle to the color transform.

If this function fails, the return value is NULL. For extended error information, call GetLastError.

Remarks

If a device link profile is being used, the function will fail if nProfiles is not set to 1.

The array of intents specifies how profiles should be combined. The nth intent is used for combining the nth profile in the array. If only one intent is specified, it is used for the first profile, and all other profiles are combined using Absolute Colorimetric intent.

The values in dwFlags are intended as hints only. The color management module must determine the best way to use them.

The CreateMultiProfileTransform function is used outside of a DC. Colors may shift when transforming from a color profile to the same color profile. This is due to precision errors. Therefore, a color transform should not be performed under these circumstances.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, The COLOR Structure, DeleteColorTransform


CreateProfileFromLogColorSpace

The CreateProfileFromLogColorSpace function converts a logical color space to a device profile.

BOOL WINAPI CreateProfileFromLogColorSpace(
  LPLOGCOLORSPACE pLogColorSpace,
  PBYTE *pBuffer
);

Parameters

pLogColorSpace
A pointer to a logical color space structure. See LOGCOLORSPACE for details. The lcsFilename[0] member of the structure must be set to the null character ('\0') or this function call will fail with the return value of INVALID_PARAMETER.
pBuffer
A pointer to a pointer to a buffer where the device profile will be created. This function allocates the buffer and fills it with profile information if it is successful. If not, the pointer is set to NULL. The caller is responsible for freeing this buffer when it is no longer needed.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

If the lcsFilename[0] member if the LOGCOLORSPACE structure pointed to by pLogColorSpace is not '\0', this function returns INVALID_PARAMETER.

Remarks

This function can be used with ASCII or Unicode strings. The buffer created by this function must be freed by the caller when it is no longer needed or there will be a memory leak. The GlobalFree function should be used to free this buffer.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, GlobalFree


DeleteColorSpace

The DeleteColorSpace function removes and destroys a specified color space.

BOOL WINAPI DeleteColorSpace(
  HCOLORSPACE hColorSpace
);

Parameters

hColorSpace
Specifies the handle to a color space to delete.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


DeleteColorTransform

The DeleteColorTransform function deletes a given color transform.

BOOL WINAPI DeleteColorTransform(
  HTRANSFORM hColorTransform
);

Parameters

hColorTransform
Identifies the color transform to delete

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, The COLOR Structure, CreateMultiProfileTransform


DisassociateColorProfileFromDevice

The DisassociateColorProfileFromDevice function disassociates a specified color profile with a specified device on a specified computer.

BOOL WINAPI DisassociateColorProfileFromDevice(
  PCTSTR pMachineName,
  PCTSTR pProfileName,
  PCTSTR pDeviceName
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the computer on which to disassociate the specified profile and device. A NULL pointer indicates the local computer.
pProfileName
Pointer to the file name of the profile to disassociate.
pDeviceName
Pointer to the name of the device to disassociate.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


EnumColorProfiles

The EnumColorProfiles function enumerates all the profiles satisfying the given enumeration criteria.

BOOL WINAPI EnumColorProfiles(
  PCTSTR pMachineName,
  PENUMTYPE pEnumRecord,
  PBYTE pBuffer,
  PDWORD pdwSize,
  PDWORD pnProfiles
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the computer on which to enumerate profiles. A NULL pointer indicates the local computer.
pEnumRecord
Pointer to a structure specifying the enumeration criteria.
pBuffer
Pointer to a buffer in which the profiles are to be enumerated. A MULTI_SZ string of profile names satisfying the criteria specified in *pEnumRecord will be placed in this buffer.
pdwSize
Pointer to a variable containing the size of the buffer pointed to by pBuffer. On return, *pdwSize contains the size of buffer actually used or needed.
pnProfile
Pointer to a variable that will contain, on return, the number of profile names actually copied to the buffer.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

The EnumColorProfiles function can be used to find the default profile for a device by specifying the device's name and profile class in the pEnumRecord parameter.

If the dwFields member of the structure of type ENUMTYPE that is pointed to by the pEnumRecord parameter is set to ET_DEVICENAME, this function will enumerate all of the color profiles associated with all types of devices attached to the user's computer. If the dwFields member of the structure pointed to by the pEnumRecord parameter is set to ET_DEVICENAME | ET_DEVICECLASS and a device class is specified in the dwDeviceClass member of the structure, this function will only enumerate the profiles associated with the specified device class. If the dwFields member is set only to ET_DEVICECLASS, the EnumColorProfiles function will enumerate all profiles that can be associated with that type of device.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, ENUMTYPE


EnumICMProfiles

The EnumICMProfiles function enumerates the different output color profiles that the system supports for a given device context.

int WINAPI EnumICMProfiles(
  HDC hDC,
  ICMENUMPROC lpEnumICMProfilesFunc,
  LPARAM lParam
);

Parameters

hDC
Specifies the device context.
lpEnumICMProfilesFunc
Specifies the procedure instance address of a callback function defined by the application. (See EnumICMProfilesProcCallback.)
lParam
Data supplied by the application that is passed to the callback function along with the color profile information.

Return Values

This function returns zero if the application interrupted the enumeration. The return value is -1 if there are no color profiles to enumerate. Otherwise, the return value is the last value returned by the callback function.

Remarks

The EnumICMProfiles function returns a list of profiles that are associated with a device context (DC), and whose settings match those of the DC. It is possible for a device context to contain device profiles that are not associated with particular hardware devices, or device profiles that do not match the settings of the DC. The sRGB profile is an example. The SetICMProfile function is used to associate these types of profiles with a DC. The GetICMProfile function can be used to retrieve a profile that is not enumerated by the EnumICMProfiles function.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, EnumICMProfilesProcCallback, SetICMProfile, GetICMProfile


EnumICMProfilesProcCallback

The EnumICMProfilesProcCallback callback is an application-defined callback function that processes color profile data from EnumICMProfiles.

int CALLBACK EnumICMProfilesProcCallback(
  LPTSTR lpszFilename,
  LPARAM lParam
);

Parameters

lpszFilename
Pointer to the file name of the color profile.
lParam
Data supplied by the application that is passed to the callback function by the EnumICMProfiles function.

Return Values

This function must return a positive value to continue enumeration, or zero to stop enumeration. It may not return a negative value.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: User-defined.

See Also

Color Management Overview, ICM 2.0 Functions, EnumICMProfiles


GetCMMInfo

The GetCMMInfo function retrieves various information about the color management module (CMM) that created the specified color transform.

DWORD WINAPI GetCMMInfo(
  HTRANSFORM hColorTransform,
  DWORD dwInfo
);

Parameters

hColorTransform
Identifies the transform for which to find CMM information.
dwInfo
Specifies the information to be retrieved. This parameter can take one of the following constant values:
Constant | Meaning
CMM_WIN_VERSION | Retrieves the version of Windows targeted by the color management module (CMM).
CMM_DLL_VERSION | Retrieves the version number of the CMM.
CMM_IDENT | Retrieves the CMM signature registered with the International Color Consortium (ICC).

Return Values

If this function succeeds, the return value is the information specified in dwInfo.

If this function fails, the return value is zero.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetColorDirectory

(Currently planned for the next releases of Windows and Windows NT)

The GetColorDirectory function retrieves the path of the Windows COLOR directory on a specified machine.

BOOL WINAPI GetColorDirectory(
  PCTSTR pMachineName,
  PTSTR pBuffer,
  PDWORD pdwSize
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the machine on which the profile is to be installed. A NULL pointer indicates the local machine.
pBuffer
Points to the buffer in which the color directory path is to be placed.
pdwSize
Points to a variable containing the size in bytes of the buffer pointed to by pBuffer. On return, the variable contains the size of the buffer actually used or needed.

Return Values

If this function succeeds, the return value is TRUE,

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


GetColorProfileElement

The GetColorProfileElement function copies data from a specified tagged profile element of a specified color profile into a buffer.

BOOL WINAPI GetColorProfileElement(
  HPROFILE hProfile,
  TAGTYPE tag,
  DWORD dwOffset,
  PDWORD pcbSize,
  PVOID pBuffer,
  PBOOL pbReference
);

Parameters

hProfile
Specifies a handle to the color profile in question.
tag
Identifies the tagged element from which to copy.
dwOffset
Specifies the offset from the first byte of the tagged element data at which to begin copying.
pcbSize
Pointer to a variable specifying the number of bytes to copy. On return, the variable contains the number of bytes actually copied.
pBuffer
Pointer to a buffer into which the tagged element data is to be copied. The buffer must contain at least as many bytes as are specified by the variable pointed to by pcbSize. If the pBuffer pointer is set to NULL, the size of the entire tagged element data in bytes is returned in the memory location pointed to by pcbSize, and dwOffset is ignored. In this case, the function will return FALSE.
pbReference
Points to a Boolean value that is set to TRUE if more than one tag in the color profile refers to the same data as the specified tag refers to, or FALSE if not.

Return Values

If this function succeeds, the return value is nonzero

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the pBuffer pointer is set to NULL, the size of the entire tagged element data in bytes is returned in the variable pointed to by pcbSize, and dwOffset is ignored.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetColorProfileElementTag

The GetColorProfileElementTag function retrieves the tag name specified by dwIndex in the tag table of a given color profile, where dwIndex is a one-based index into that table.

BOOL WINAPI GetColorProfileElementTag(
  HPROFILE hProfile,
  DWORD dwIndex,
  PTAGTYPE pTag
);

Parameters

hProfile
Specifies a handle to the color profile in question.
dwIndex
Specifies the one-based index of the tag to retrieve.
pTag
Pointer to a variable in which the tag name is to be placed.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

GetColorProfileElementTag can be used to enumerate all tags in a profile after getting the number of tags in the profile using GetCountColorProfileElements.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetColorProfileFromHandle

Given a handle to an open color profile, the GetColorProfileFromHandle function will copy the contents of the profile into a buffer supplied by the application.

BOOL WINAPI GetColorProfileFromHandle(
  HPROFILE hProfile,
  PBYTE pBuffer,
  PDWORD pcbSize
);

Parameters

hProfile
Handle to an open color profile.
pBuffer
Pointer to buffer to receive raw profile data. Can be NULL. If it is, the size required for the buffer will be stored in the memory location pointed to by pcbSize. The buffer can be allocated to the appropriate size, and this function called again with pBuffer containing the address of the buffer.
pcbSize
Pointer to a DWORD that holds the size of buffer pointed at by pBuffer. On return it is filled with size of buffer that was actually used if the function succeeds. If this function is called with pBuffer set to NULL, this parameter will contain the size of the buffer required.

Return Values

If this function succeeds, the return value is TRUE. It also returns TRUE if the pBuffer parameter is NULL and the size required for the buffer is copied into pcbSize.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetColorProfileHeader

The GetColorProfileHeader function retrieves the header of a color profile.

BOOL WINAPI GetColorProfileHeader(
  HPROFILE hProfile,
  PPROFILEHEADER pHeader
);

Parameters

hProfile
Specifies a handle to the color profile in question.
pHeader
Points to a variable in which the header is to be placed.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, PROFILEHEADER


GetColorSpace

The GetColorSpace function retrieves the handle to the input color space from a specified device context.

HCOLORSPACE WINAPI GetColorSpace(
  HDC hDC
);

Parameters

hDC
Specifies a device context that is to have its input color space handle retrieved.

Return Values

If the function succeeds, the return value is the current input color space handle.

If this function fails, the return value is NULL.

Remarks

GetColorSpace obtains the handle to the input color space regardless of whether color management is enabled for the device context.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetCountColorProfileElements

(Currently planned for the next releases of Windows and Windows NT)

The GetCountColorProfileElements function retrieves the number of tagged elements in a given color profile.

BOOL WINAPI GetCountColorProfileElements(
  HPROFILE hProfile,
  PDWORD pnCount
);

Parameters

hProfile
Specifies a handle to the profile in question.
pnCount
Pointer to a variable in which to place the number of tagged elements in the profile.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetDeviceGammaRamp

The GetDeviceGammaRamp function gets the gamma ramp on direct color display boards having drivers that support downloadable gamma ramps in hardware.

BOOL WINAPI GetDeviceGammaRamp(
  HDC hDC,
  LPVOID lpRamp
);

Parameters

hDC
Specifies the device context of the direct color display board in question.
lpRamp
Points to a buffer where the function can place the current gamma ramp of the color display board. The gamma ramp is specified in three arrays of 256 WORD elements each, which contain the mapping between RGB values in the frame buffer and digital-analog-converter (DAC) values. The sequence of the arrays is red, green, blue.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

Remarks

Direct color display modes do not use color lookup tables and are usually 16, 24, or 32 bit. Not all direct color video boards support loadable gamma ramps. GetDeviceGammaRamp succeeds only for devices with drivers that support downloadable gamma ramps in hardware.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetICMProfile

The GetICMProfile function retrieves the file name of the current output color profile for a specified device context.

BOOL WINAPI GetICMProfile(
  HDC hDC,
  LPDWORD lpcbName,
  LPTSTR lpszFilename
);

Parameters

hDC
Specifies a device context from which to retrieve the color profile.
lpcbName
Points to a DWORD that contains the size of the buffer pointed at by lpszFilename. On return this parameter contains the size of the buffer actually used if the function is successful. If the buffer is not large enough, this function will return value FALSE. The GetLastError() function will return ERROR_INSUFFICIENT_BUFFER. The DWORD pointed to by this parameter will contain the size needed for the lpscFilename buffer.
lpszFilename
Points to the buffer that receives the path name of the profile.

Return Values

If this function succeeds, the return value is TRUE. It also returns TRUE if the lpszFilename parameter is NULL and the size required for the buffer is copied into lpcbName.

If this function fails, the return value is FALSE.

Remarks

GetICMProfile obtains the file name of the current output profile regardless of whether or not color management is enabled for the device context.

Given a device context, GetICMProfile will output, through the parameter lpszFilename, the path name of the file containing the color profile currently being used by the device context. It will also output, through the parameter lpcbName, the length of the string containing the path name.

It is possible that the profile name returned by GetICMProfile will not be in the list of profiles returned by EnumICMProfiles. The EnumICMProfiles function returns all color space profiles that are associated with a device context (DC) whose settings match that of the DC. If the SetICMProfile function is used to set the current profile, a profile may be associated with the DC that does not match its settings. For instance, the SetICMProfile function can be used to associate the device-independent sRGB profile with a DC. This profile will be used as the current ICM profile for that DC, and calls to GetICMProfile will return its file name. However, the profile will not appear in the list of profiles that is returned from EnumICMProfiles.

If this function is called before any calls to the SetICMProfile function, it can be used to get the default profile for a device context.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, EnumICMProfiles , SetICMProfile


GetLogColorSpace

The GetLogColorSpace function retrieves the color space definition identified by a specified handle.

BOOL WINAPI GetLogColorSpace(
  HCOLORSPACE hColorSpace,
  LPLOGCOLORSPACE lpBuffer,
  DWORD nSize
);

Parameters

hColorSpace
Specifies the handle to a color space.
lpBuffer
Points to a buffer to receive the LOGCOLORSPACE structure.
nSize
Specifies the maximum size of the buffer.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


GetNamedProfileInfo

The GetNamedProfileInfo function retrieves information about the specified named color profile.

BOOL WINAPI GetNamedProfileInfo(
  HPROFILE hProfile,
  PNAMED_PROFILE_INFO pNamedProfileInfo
);

Parameters

hProfile
The handle to the profile from which the information will be retrieved.
pNamedProfileInfo
A pointer to a NAMED_PROFILE_INFO structure

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, NAMED_PROFILE_INFO


GetPS2ColorRenderingDictionary

The GetPS2ColorRenderingDictionary function retrieves the PostScript Level 2 color rendering dictionary from the specified profile.

BOOL WINAPI GetPS2ColorRenderingDictionary(
  HPROFILE hProfile,
  DWORD dwIntent,
  PBYTE pBuffer,
  PDWORD pcbSize,
  PBOOL pbBinary
);

Parameters

hProfile
Specifies a handle to the profile in question.
dwIntent
Specifies the desired rendering intent for the color rendering dictionary. Valid values are:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

pBuffer
Pointer to a buffer in which the color rendering dictionary is to be placed. If the pBuffer pointer is set to NULL, the required buffer size is returned in *pcbSize.
pcbSize
Pointer to a variable containing the size of the buffer in bytes. On return, the variable contains the number of bytes actually copied.
pbBinary
Pointer to a Boolean variable. If TRUE, the color rendering dictionary could be copied in binary form. If FALSE, the dictionary will be encoded in ASCII85 form. On return, this Boolean variable indicates whether the dictionary was actually binary (TRUE) or ASCII85 (FALSE).

Return Values

If this function succeeds, the return value is TRUE. It also returns TRUE if the pBuffer parameter is NULL and the size required for the buffer is copied into pcbSize.

If this function fails, the return value is FALSE.

Remarks

If the dictionary is not available in the profile, the GetPS2ColorRenderingDictionary function builds one using the profile contents. This dictionary can then be used as the operand for the PostScript Level 2 setcolorrendering operator.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetPS2ColorRenderingIntent

The GetPS2ColorRenderingIntent function retrieves the PostScript Level 2 color rendering intent from a profile.

BOOL WINAPI GetPS2ColorRenderingIntent(
  HPROFILE hProfile,
  DWORD dwIntent,
  PBYTE pBuffer,
  PDWORD pcbSize
);

Parameters

hProfile
Specifies a handle to the profile in question.
dwIntent
Specifies the desired rendering intent to retrieve. Valid values are:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

pBuffer
Points to a buffer in which the color rendering intent is to be placed. If the pBuffer pointer is set to NULL, the buffer size required is returned in *pcbSize.
pcbSize
Points to a variable containing the buffer size in bytes. On return, this variable contains the number of bytes actually copied.

Return Values

If this function succeeds, the return value is TRUE. If this function succeeds, the return value is TRUE. It also returns TRUE if the pBuffer parameter is NULL and the size required for the buffer is copied into pcbSize.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

The rendering intent returned by GetPS2ColorRenderingIntent can be used as the operand for the PostScript Level 2 findcolorrendering operator.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetPS2ColorSpaceArray

The GetPS2ColorSpaceArray function retrieves the PostScript Level 2 color space array from a profile.

BOOL WINAPI GetPS2ColorSpaceArray(
  HPROFILE hProfile,
  DWORD dwIntent,
  DWORD dwCSAType,
  PBYTE pBuffer,
  PDWORD pcbSize,
  PBOOL pbBinary
);

Parameters

hProfile
Specifies a handle to the profile from which to retrieve the PostScript Level 2 color space array.
dwIntent
Specifies the desired rendering intent for the color space array. This field may take one of the following values:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

dwCSAType
Specifies the type of color space array. Can take one of the following constant values:
Constant | Meaning
CSA_A | Get a CIEBasedA color space array from the monochrome profile.
CSA_GRAY | Get a CIEBasedA color space array from the monochrome profile.
CSA_ABC | Get a CIEBasedABC color space array from the RGB or L*a*b* profile.
CSA_DEF | Get a CIEBasedDEF color space array from the RGB or L*a*b* profile.
CSA_RGB | Get a CIEBasedDEF color space array followed by a CIEBasedABC color space array from the RGB profile. On execution, if the printer doesn't support CIEBasedDEF color spaces, the function uses the CIEBasedABC definition.
CSA_Lab | Gets a CIEBasedABC color space array from the L*a*b* profile.
CSA_DEFG | Get a CIEBasedDEFG color space array from the CMYK profile.
CSA_CMYK | Get a CIEBasedCMYK color space array from the CMYK profile.

pBuffer
Pointer to a buffer in which the color space array is to be placed. If the pBuffer pointer is set to NULL, the function returns the required size of the buffer in the memory location pointed to by pcbSize.
pcbSize
Pointer to a variable containing the size of the buffer in bytes. On return, it contains the number of bytes copied into the buffer.
pbBinary
Pointer to a Boolean variable. If set to TRUE, the data copied could be binary. If set to FALSE, data should be encoded as ASCII85. On return, the memory location pointed to by pbBinary indicates whether the data returned actually is binary (TRUE) or ASCII85 (FALSE).

Return Values

If this function succeeds, the return value is TRUE. If this function succeeds, the return value is TRUE. It also returns TRUE if the pBuffer parameter is NULL and the size required for the buffer is copied into pcbSize.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the color space array is not available in the profile, the GetPS2ColorSpaceArray function builds a PostScript Level 2 color space array using the profile contents. This array can then be used as the operand for the PostScript Level2 setcolorspace operator.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


GetStandardColorSpaceProfile

The GetStandardColorSpaceProfile function retrieves the color profile registered for the specified standard color space.

BOOL WINAPI GetStandardColorSpaceProfile(
  PCTSTR pMachineName,
  DWORD dwProfileID,
  PTSTR pProfileName,
  PDWORD pdwSize
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the computer on which to get a standard color space profile. A NULL pointer indicates the local machine.
dwProfileID
Specifies the ID value of the standard color space for which to retrieve the profile.
pProfileName
Pointer to the buffer in which the name of the profile is to be placed. If NULL, the call will return FALSE and the required size of the buffer is placed in pdwSize.
pdwSize
Pointer to a variable containing the size in bytes of the buffer pointed to by pProfileName. On return, the variable contains the size of the buffer actually used or needed.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the buffer pointed to by pProfileName is to be dynamically allocated by an application, the application can call the GetStandardColorSpaceProfile function to retrieve the size required for the buffer. If GetStandardColorSpaceProfile is called with pProfileName set to NULL, it will return FALSE and the DWORD pointed at by pdwSize will contain the number of bytes needed for the buffer pointed at by pProfileName. The application can then allocate the buffer and call GetStandardColorSpaceProfile again with pProfileName set to the address of the buffer.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, SetStandardColorSpaceProfile


ICMProgressProcCallback

The ICMProgressProcCallback function is an application-supplied callback function that reports progress and permits the application to cancel color processing.

BOOL WINAPI ICMProgressProcCallback(
  ULONG ulMax,
  ULONG ulCurrent,
  ULONG ulCallbackData
);

Parameters

ulMax
Specifies the maximum value of the progress counter (used to estimate completion of the bitmap processing).
ulCurrent
Specifies the current value of the progress counter (when divided by the maximum value, provides a rough estimate of percentage of completion).
ulCallbackData
Specifies the data which is passed by the application to an ICM function, which then passes it on to the callback function. Such data can be used, for example, to identify the bitmap and process about which progress is being reported.

Return Values

This function returns TRUE to continue bitmap processing. The return value is FALSE to cancel processing. If processing is canceled, the calling function returns zero to indicate failure, although its output buffer may be partially filled.

Remarks

The name of this callback function is supplied by the application. A number of ICM functions, including TranslateBitmapBits and CheckBitmapBits, call this function periodically.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: User-defined.

See Also

Color Management Overview, ICM 2.0 Functions, TranslateBitmapBits, CheckBitmapBits


InstallColorProfile

(Currently planned for the next releases of Windows and Windows NT)

The InstallColorProfile function installs a given profile for use on a specified machine. The profile is also copied to the COLOR directory.

BOOL WINAPI InstallColorProfile(
  PCTSTR pMachineName,
  PCTSTR pProfileName
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the computer on which the profile is to be installed. A NULL pointer indicates the local computer.
pProfileName
Pointer to the fully qualified path name of the profile to install.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


IsColorProfileTagPresent

The IsColorProfileTagPresent function reports whether a specified International Color Consortium (ICC) tag is present in the specified color profile.

BOOL WINAPI IsColorProfileTagPresent(
  HPROFILE hProfile,
  TAGTYPE tag,
  PBOOL pbPresent
);

Parameters

hProfile
Specifies a handle to the profile in question.
tag
Specifies the ICC tag to check.
pbPresent
Pointer to a variable that is set to TRUE on return if the specified ICC tag is present , or FALSE if not.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


IsColorProfileValid

The IsColorProfileValid function allows an application to determine whether the specified profile is a valid International Color Consortium (ICC) profile that can be used for color management.

BOOL WINAPI IsColorProfileValid(
  HPROFILE hProfile,
  PBOOL pbValid
);

Parameters

hProfile
Specifies a handle to the profile to be validated.
pbValid
Pointer to a variable that is set to TRUE on return if the profile is a valid ICC profile, or FALSE if not.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


OpenColorProfile

The OpenColorProfile function creates a handle to a specified color profile. The handle can then be used in other profile management functions.

HPROFILE WINAPI OpenColorProfile(
  PPROFILE pProfile,
  DWORD dwDesiredAccess,
  DWORD dwShareMode,
  DWORD dwCreationMode
);

Parameters

pProfile
Pointer to a color profile structure specifying the profile.
dwDesiredAccess
Specifies how to access the given profile. This parameter must take one the following constant values:
Constant | Meaning
PROFILE_READ | Opens the profile for read access.
PROFILE_READWRITE | Opens the profile for both read and write access.

dwShareMode
Specifies how the profile should be shared, if the profile is contained in a file. A value of zero prevents the profile from being shared at all. The parameter can contain one or both of the following constants (combined by addition or logical OR):
Constant | Meaning
FILE_SHARE_READ | Other open operations can be performed on the profile for read access.
FILE_SHARE_WRITE | Other open operations can be performed on the profile for write access.

dwCreationMode
Specifies which actions to take on the profile while opening it, if it is contained in a file. This parameter must take one of the following constant values:
Constant | Meaning
CREATE_NEW | Creates a new profile. Fails if the profile already exists.
CREATE_ALWAYS | Creates a new profile. Overwrites the profile if it exists.
OPEN_EXISTING | Opens the profile. Fails if it does not exist
OPEN_ALWAYS | Opens the profile if it exists. If it does not exist, creates the profile.
TRUNCATE_EXISTING | Opens the profile, and truncates it to zero bytes. Fails if the profile doesn't exist.

Return Values

If this function succeeds, the return value is the handle of the color profile that is opened.

If this function fails, the return value is NULL. For extended error information, call GetLastError.

Remarks

If the profile data is not specified using a file name, dwShareMode and dwCreationMode are ignored.

Use the CloseColorProfile function to close an object handle returned by OpenColorProfile.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, CloseColorProfile, PROFILE


RegisterCMM

RegisterCMM associates a specified identification value with the specified color management module dynamic link library (CMM DLL). When this ID appears in a color profile, Windows can then locate the corresponding CMM so as to create a transform.

BOOL WINAPI RegisterCMM(
  PCTSTR pMachineName,
  DWORD cmmID,
  PCTSTR pCMMdll
);

Parameters

pMachineName
Reserved for future use; must currently be set to NULL, until non-local registration is supported. This parameter is intended to point to the name of the machine on which a CMM DLL should be registered. A NULL pointer indicates the local machine.
cmmID
Specifies the ID signature of the CMM registered with the International Color Consortium (ICC).
pCMMdll
Pointer to the fully qualified path name of the CMM DLL.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


SelectCMM

SelectCMM allows an application to select the preferred color management module (CMM) to use.

BOOL WINAPI SelectCMM(
  DWORD cmmID
);

Parameters

cmmID
Specifies the signature of the desired CMM as registered with the International Color Consortium (ICC).

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

For SelectCMM to succeed, the specified CMM must be registered with the system.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


SetColorProfileElement

The SetColorProfileElement function sets the element data for a tagged profile element.

BOOL WINAPI SetColorProfileElement(
  HPROFILE hProfile,
  TAGTYPE tag,
  DWORD dwOffset,
  PDWORD pcbSize,
  PVOID pBuffer
);

Parameters

hProfile
Specifies a handle to the profile in question.
tag
Identifies the tagged element.
dwOffset
Specifies the offset from the first byte of the tagged element data at which to start writing.
pcbSize
Pointer to a variable containing the number of bytes of data to write. On return, it contains the number of bytes actually written.
pBuffer
Pointer to a buffer containing the data to write to the tagged element in the color profile.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the color profile is not opened for read/write permission, this function fails.

If dwOffset exceeds the size set for the specified tagged element, this function fails.

If dwOffset + *pcbSize is greater than the size of the specified element, this function only writes as many bytes as will fit within the current size of the element.

Any existing data in the specified portion of the tagged element is overwritten when this function succeeds.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


SetColorProfileElementReference

SetColorProfileElementReference creates in a specified color profile a new tag which references the same data as an existing tag.

BOOL WINAPI SetColorProfileElementReference(
  HPROFILE hProfile,
  TAGTYPE newTag,
  TAGTYPE refTag
);

Parameters

hProfile
Specifies a handle to the color profile in question.
newTag
Identifies the new tag to create.
refTag
Identifies the existing tag whose data is to be referenced by the new tag.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If newTag already exists or refTag does not exist, SetColorProfileElementReference fails.

If the color profile was not opened with read/write permission, SetColorProfileElementReference fails.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


SetColorProfileElementSize

SetColorProfileElementSize sets the size of a tagged element.

BOOL WINAPI SetColorProfileElementSize(
  HPROFILE hProfile,
  TAGTYPE tag,
  DWORD cbSize
);

Parameters

hProfile
Specifies a handle to the color profile in question.
tag
Identifies the tagged element.
cbSize
Specifies the size to set the tagged element to. If cbSize is zero, this function deletes the specified tagged element. If the tag is a reference, only the tag table entry is deleted, not the data.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

To create a new tagged element in a color profile, use SetColorProfileElementSize to set the size, then use SetColorProfileElement to set the element value.

If the specified tag already exists in the profile, SetColorProfileElementSize changes the size of the element by truncating it or adding zeroes at the end as the case may be.

If the specified tag already exists and is a reference to another tag, SetColorProfileElementSize creates a new data area for the tag that is not shared.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, SetColorProfileElement


SetColorProfileHeader

The SetColorProfileHeader function sets the header data in a specified color profile.

BOOL WINAPI SetColorProfileHeader(
  HPROFILE hProfile,
  PPROFILEHEADER pHeader
);

Parameters

hProfile
Specifies a handle to the color profile in question.
pHeader
Pointer to the profile header data to write to the specified profile.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the color profile was not opened with read/write permission, SetColorProfileHeader fails.

SetColorProfileHeader overwrites the current header in the profile.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, PROFILEHEADER


SetColorSpace

The SetColorSpace function defines the input color space for a given device context.

HCOLORSPACE WINAPI SetColorSpace(
  HCD hDC,
  HCOLORSPACE hColorSpace
);

Parameters

hDC
Specifies the handle to a device context.
hColorSpace
Identifies handle to the color space to set.

Return Values

If this function succeeds, the return value is a handle to the hColorSpace being replaced.

If this function fails, the return value is NULL.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


SetDeviceGammaRamp

The SetDeviceGammaRamp function sets the gamma ramp on direct color display boards having drivers that support downloadable gamma ramps in hardware.

BOOL WINAPI SetDeviceGammaRamp(
  HDC hDC,
  LPVOID lpRamp
);

Parameters

hDC
Specifies the device context of the direct color display board in question.
lpRamp
Pointer to a buffer containing the gamma ramp to be set. The gamma ramp is specified in three arrays of 256 WORD elements each, which contain the mapping between RGB values in the frame buffer and digital-analog-converter (DAC) values. The sequence of the arrays is red, green, blue.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

Remarks

Direct color display modes do not use color lookup tables and are usually 16, 24, or 32 bit. Not all direct color video boards support loadable gamma ramps. SetDeviceGammaRamp succeeds only for devices with drivers that support downloadable gamma ramps in hardware.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions


SetICMMode

The SetICMMode function causes Image Color Management to be enabled, disabled, or queried on a given device context (DC).

int WINAPI SetICMMode(
  HDC hDC,
  int iEnableICM
);

Parameters

hDC
Identifies handle to the device context.
iEnableICM
Turns on and off image color management. This parameter can take one of the following constant values.
Constant | Meaning
ICM_ON | Turns on color management. Turns off old-style color correction of halftones.
ICM_OFF | Turns off color management. Turns on old-style color correction of halftones.
ICM_QUERY | Queries the current state of color management.
ICM_DONE_OUTSIDEDC | Turns off color management inside DC. Under Windows NT 5.0 or later, also turns off old-style color correction of halftones. Not supported under Windows 95.

Return Values

If this function succeeds, the return value is a nonzero value.

If this function fails, the return value is zero.

If ICM_QUERY is specified and the function succeeds, the nonzero value returned is ICM_ON or ICM_OFF to indicate the current mode.

Remarks

If the system cannot find an ICC color profile to match the state of the device, SetICMMode fails and returns zero.

Once ICM is enabled for a device context (DC), colors passed into the DC using most Win32 API functions are color matched. The primary exceptions are BitBlt and StretchBlt. The assumption is that when performing a bit block transfer (blit) from one DC to another, the two DCs are already compatible and need no color correction. If this is not the case, color correction may be performed. Specifically, if a device independent bitmap (DIB) is used as the source for a blit, and the blit is performed into a DC that has ICM enabled, color matching will be performed. If this is not what you want, turn ICM off for the destination DC by calling SetICMMode before calling BitBlt or StretchBlt.

If the CreateCompatibleDC function is used to create a bitmap in a DC, it is possible for the bitmap to be color matched twice, once when it is created and once when a blit is performed. The reason is that a bitmap in a DC created by the CreateCompatibleDC function acquires the current brush, pens, and palette of the source DC. However, ICM will be disabled by default for the new DC. If ICM is later enabled for the new DC by using the SetICMMode function, a color correction will be done. To prevent double color corrections through the use of the CreateCompatibleDC function, use the SetICMMode function to turn ICM off for the source DC before the CreateCompatibleDC function is called.

When a compatible DC is created from a printer's DC (see CreateCompatibleDC), the default is for color matching to always be performed if it is enabled for the printer's DC. The default color profile for the printer is used when a blit is performed into the printer's DC using SetDIBitsToDevice or StretchDIBits. If this is not what you want, turn ICM off for the printer's DC by calling SetICMMode before calling SetDIBitsToDevice or StretchDIBits.

Also, when printing to a printer's DC with ICM turned on, the SetICMMode function needs to be called after every call to the StartPage function to turn back on ICM. The StartPage function calls the RestoreDC and SaveDC functions, which result in ICM being turned off for the printer's DC.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, BitBlt, StretchBlt, CreateCompatibleDC, SetDIBitsToDevice, StretchDIBits, StartPage


SetICMProfile

The SetICMProfile function sets a specified color profile as the output profile for a specified device context (DC).

BOOL WINAPI SetICMProfile(
  HDC hDC,
  LPTSTR lpFileName
);

Parameters

hDC
Specifies a device context in which to set the color profile.
lpFileName
Specifies the path name of the color profile to be set.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

Remarks

SetICMProfile associates a color profile with a device context. It becomes the output profile for that device context. The color profile does not have to be associated with any particular device. Device-independent profiles such as sRGB can also be used. If the color profile is not associated with a hardware device, it will be returned by GetICMProfile, but not by EnumICMProfiles.

Note that under Windows 95 or later, the PostScript device driver for printers assumes a CMYK color model. Therefore, all PostScript printers must use a CMYK color profile. Windows NT does not have this limitation.

SetICMProfile supports only RGB profiles in compatible DCs.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use gdi32.lib.

See Also

Color Management Overview, ICM 2.0 Functions, GetICMProfile, EnumICMProfiles


SetStandardColorSpaceProfile

The SetStandardColorSpaceProfile function registers a specified profile for a given standard color space. The profile can be queried using GetStandardColorSpaceProfile.

BOOL WINAPI SetStandardColorSpaceProfile(
  PCTSTR pMachineName,
  DWORD dwProfileID,
  PCSTR pProfilename
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the machine on which to set a standard color space profile. A NULL pointer indicates the local machine.
dwProfileID
Specifies the ID value of the standard color space that the given profile represents.
pProfilename
Points to a fully qualified path to the profile file.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

The profile must already be installed on the system before it can be registered for a standard color space.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions, GetStandardColorSpaceProfile


SetupColorMatching

The SetupColorMatching function creates a Color Management dialog box that lets the user choose whether to enable color management, and if so, provides control over the color profiles used and over the rendering intent.

BOOL WINAPI SetupColorMatching(
  PCOLORMATCHSETUP pcms
);

Parameters

pcms
Pointer to a COLORMATCHSETUP structure that on entry contains information used to initialize the dialog box.

When SetupColorMatching returns, if the user clicked the OK button, this structure contains information about the user's selection. Otherwise, if an error occurred or the user canceled the dialog box, the structure is left unchanged.

Return Values

If this function succeeds, the return value is TRUE indicating that no errors occurred and the user clicked the OK button.

If this function fails, the return value is FALSE indicating that an error occurred or the dialog was canceled. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use icmui.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


TranslateBitmapBits

The TranslateBitmapBits function translates the colors of a bitmap having a defined format so as to produce another bitmap in a requested format.

BOOL WINAPI TranslateBitmapBits(
  HTRANSFORM hColorTransform,
  PVOID pSrcBits,
  BMFORMAT bmInput,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwInputStride,
  PVOID pDestBits,
  BMFORMAT bmOutput,
  DWORD dwOutputStride,
  PBMCALLBACKFN pfnCallback,
  ULONG ulCallbackData
);

Parameters

hColorTransform
Identifies the color transform to use.
pSrcBits
Pointer to the bitmap to translate.
bmInput
Specifies the format of the input bitmap. Must be set to one of the values of the BMFORMAT enumerated type.
dwWidth
Specifies the number of pixels per scan line in the input bitmap.
dwHeight
Specifies the number of scan lines in the input bitmap.
dwInputStride
Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the input bitmap; if set to zero, the function assumes that scan lines are padded so as to be DWORD-aligned.
pDestBits
Pointer to the buffer in which to place the translated bitmap.
bmOutput
Specifies the format of the output bitmap. Must be set to one of the values of the BMFORMAT enumerated type.
dwOutputStride
Specifies the number of bytes from the beginning of one scan line to the beginning of the next in the output bitmap; if set to zero, the function assumes that scan lines should be padded to be DWORD-aligned.
pfnCallback
Pointer to a callback function called periodically by TranslateBitmapBits to report progress and allow the calling process to cancel the translation. (See ICMProgressProcCallback)
ulCallbackData
Data passed back to the callback function, for example, to identify the translation that is reporting progress.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the input and output formats are not compatible with the color transform, this function fails.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions, ICMProgressProcCallback, Windows Bitmap Header Structures, BMFORMAT


TranslateColors

The TranslateColors function translates an array of colors from the source color space to the destination color space as defined by a color transform.

BOOL WINAPI TranslateColors(
  HTRANSFORM hColorTransform,
  PCOLOR paInputColors,
  DWORD nColors,
  COLORTYPE ctInput,
  PCOLOR paOutputColors,
  COLORTYPE ctOutput
);

Parameters

hColorTransform
Identifies the color transform to use.
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.
paOutputColors
Pointer to an array of nColors COLOR structures that receive the translated colors.
ctOutput
Specifies the output color type.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the input and the output color types are not compatible with the color transform, this function fails.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.

See Also

Color Management Overview, ICM 2.0 Functions


UninstallColorProfile

UninstallColorProfile removes a specified color profile from a specified computer. Associated files are optionally deleted from the system.

BOOL WINAPI UninstallColorProfile(
  PCTSTR pMachineName,
  PCTSTR  pProfileName,
  BOOL bDelete
);

Parameters

pMachineName
Reserved for future use; must be NULL. This parameter is intended to point to the name of the machine from which to uninstall the specified profile. A NULL pointer indicates the local machine.
pProfileName
Points to the fully qualified path name of the profile to uninstall.
bDelete
If set to TRUE, the function deletes the profile from the COLOR directory.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


UnregisterCMM

The UnregisterCMM function dissociates a specified ID value from a given color management module dynamic-link library (CMM DLL).

BOOL WINAPI UnregisterCMM(
  PCTSTR pMachineName,
  DWORD cmmID
);

Parameters

pMachineName
Reserved for future use; must currently be set to NULL, until non-local registration is supported. This parameter is intended to point to the name of the computer on which a CMM DLLs registration should be removed. A NULL pointer indicates the local computer .
cmmID
Specifies the ID value identifying the CMM whose registration is to be removed. This is the signature of the CMM registered with the International Color Consortium (ICC).

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE. For extended error information, call GetLastError.

Remarks

If the profile for creating a transform later specifies this ID, the Windows default CMM will be used rather than this CMM DLL.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Import Library: Use mscms.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, ICM 2.0 Functions


Obsolete ICM Functions

This section delineates functions that are obsolete in ICM 2.0. They are currently kept for backward compatibility. However, they will be removed from the API in future releases of ICM.

UpdateICMRegKey Obsolete: manages color profiles and CMMs.


UpdateICMRegKey

(Obsolete; retained in future versions of Windows and Windows NT for compatibility)

The UpdateICMRegKey function manages color profiles and Color Management Modules in the system.

BOOL UpdateICMRegKey(
  DWORD dwReserved,
  LPTSTR lpszCMID,
  LPTSTR lpszFileName,
  UINT nCommand
);

Parameters

dwReserved
Reserved, must be set to zero.
lpszCMID
Points to a string that specifies the ICC profile identifier for the color management DLL to use with the profile.
lpszFileName
Points to a fully qualified ICC color profile file name or to a DEVMODE structure.
nCommand
Specifies a function to execute. It can have one of the following values:
ICM_ADDPROFILE | Installs the ICC profile in the system.
ICM_DELETEPROFILE | Uninstalls the ICC profile from the system, but does not delete the file.
ICM_QUERYPROFILE | Determines whether the profile is already installed in the system.
ICM_SETDEFAULTPROFILE | Makes the profile first among equals.
ICM_REGISTERICMATCHER | Registers a CMM in the system. The pszFileName parameter points to a fully qualified path for the CMM DLL. The lpszCMID parameter points to a DWORD identifying the CMM.
ICM_UNREGISTERICMATCHER | Unregisters the CMM from the system. The lpszCMID parameter points to a DWORD identifying the CMM.
ICM_QUERYMATCH | Determines whether a profile exists based on the DEVMODE structure pointed to by the pszFileName parameter.

Return Values

If this function succeeds, the return value is TRUE.

If this function fails, the return value is FALSE.

Remarks

Not all parameters are used by all functions. The nCommand parameter specifies the function to execute.

This function is retained for backward compatibility and will be removed in the future.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Import Library: Use gdi32.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.

See Also

Color Management Overview, Obsolete ICM Functions


ICM 2.0 Enumerations

This section of the reference contains an alphabetical listing of the most important enumerations that are used by ICM 2.0:

  • BMFORMAT
  • COLORTYPE


BMFORMAT

The values of the BMFORMAT enumerated type are used by several ICM functions to indicate the format that particular bitmaps are in. The enumeration defines the following values:

Value | Meaning
BM_1GRAY | 1 bit per pixel.
BM_x555RGB | 16 bits per pixel. RGB color space. 5 bits per channel. The most significant bit is ignored.
BM_x555XYZ | 16 bits per pixel. CIE device-independent XYZ color space. 5 bits per channel. The most significant bit is ignored.
BM_x555Yxy | 16 bits per pixel. Yxy color space. 5 bits per channel. The most significant bit is ignored.
BM_x555Lab | 16 bits per pixel. L*a*b color space. 5 bits per channel. The most significant bit is ignored.
BM_x555G3CH | 16 bits per pixel. G2CH color space. 5 bits per channel. The most significant bit is ignored.
BM_RGBTRIPLETS | 32 bits per pixel. 8 bits are for grayscale, and 8 bits apiece are used for the red, green, and blue values.
BM_BGRTRIPLETS | 32 bits per pixel. 8 bits are for grayscale, and 8 bits apiece are used for the blue, green, and red values.
BM_XYZTRIPLETS | 32 bits per pixel. 8 bits are for grayscale, and 8 bits apiece are used for the X, Y, and Z values.
BM_YxyTRIPLETS | 32 bits per pixel. 8 bits are for grayscale, and 8 bits apiece are used for the Y, x, and y values.
BM_LabTRIPLETS | 32 bits per pixel. 8 bits are for grayscale, and 8 bits apiece are used for the L, a, and b values.
BM_G3CHTRIPLETS | 32 bits per pixel. 8 bits are for grayscale, and 8 bits apiece are used for the color channel values.
BM_8GRAY | 32 bits per pixel. Only the 8 bit grayscale value is used.
BM_xRGBQUADS | 32 bits per pixel. 8 bits are used for each color channel. The most significant byte is ignored.
BM_xBGRQUADS | 32 bits per pixel. 8 bits are used for each color channel. The most significant byte is ignored.
BM_xG3CHQUADS | 32 bits per pixel. 8 bits are used for each color channel. The most significant byte is ignored.
BM_CMYKQUADS | 32 bits per pixel. 8 bits are used for each color channel.
BM_10b_RGB | 32 bits per pixel. 10 bits are used for each color channel. The 2 most significant bits are ignored.
BM_10b_XYZ | 32 bits per pixel. 10 bits are used for each color channel. The 2 most significant bits are ignored.
BM_10b_Yxy | 32 bits per pixel. 10 bits are used for each color channel. The 2 most significant bits are ignored.
BM_10b_Lab | 32 bits per pixel. 10 bits are used for each color channel. The 2 most significant bits are ignored.
BM_10b_G3CH | 32 bits per pixel. 10 bits are used for each color channel. The 2 most significant bits are ignored.
BM_16b_RGB | 64 bits per pixel. 16 bits are used for the grayscale value. Each of the 3 color channels uses 16 bits.
BM_16b_XYZ | 64 bits per pixel. 16 bits are used for the grayscale value. Each of the 3 color channels uses 16 bits.
BM_16b_Yxy | 64 bits per pixel. 16 bits are used for the grayscale value. Each of the 3 color channels uses 16 bits.
BM_16b_Lab | 64 bits per pixel. 16 bits are used for the grayscale value. Each of the 3 color channels uses 16 bits.
BM_16b_G3CH | 64 bits per pixel. 16 bits are used for the grayscale value. Each of the 3 color channels uses 16 bits.
BM_16b_GRAY | 64 bits per pixel. 16 bits are used for the grayscale value. All other bits are ignored.
BM_565RGB | 16 bits per pixel. 5 bits are used for red, 6 for green, and 5 for blue.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.


COLORTYPE

The values of the COLORTYPE enumeration are used by several ICM functions. Variables of type COLOR are defined in the color spaces enumerated by the COLORTYPE enumeration. The enumeration defines the following values:

Value | Meaning
COLOR_GRAY | The COLOR is in the GRAYCOLOR color space.
COLOR_RGB | The COLOR is in the RGBCOLOR color space.
COLOR_CMYK | The COLOR is in the CMYKCOLOR color space
COLOR_XYZ | The COLOR is in the XYZCOLOR color space.
COLOR_Yxy | The COLOR is in the YxyCOLOR color space.
COLOR_Lab | The COLOR is in the LabCOLOR color space.
COLOR_3_CHANNEL | The COLOR is in the GENERIC3CHANNEL color space.
COLOR_5_CHANNEL | The COLOR is in a five channel color space
COLOR_6_CHANNEL | The COLOR is in a six channel color space.
COLOR_7_CHANNEL | The COLOR is in a seven channel color space.
COLOR_8_CHANNEL | The COLOR is in an eight channel color space.
COLOR_NAMED | The COLOR is in a named color space.

Note In addition to managing the common two, three, and four channel color spaces, ICM 2.0 is able to do color management with device profiles that contain five through eight color channels. It is also able to use named color spaces. When five, six, seven, or eight color channels are used, the provider of the device profile is free to determine what the color channels represent. The same is true of named color spaces. ICM 2.0 is able to manage these color spaces as long as there is a mapping in the device profile that maps the channels or the name space into the PCS. The device profile must also contain a mapping from the PCS into the five, size, seven, or eight channel space, or into the named color space.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.


ICM 2.0 Structures

This section of the reference contains a listing of the most important structures that are used by ICM 2.0. These are listed as follows:

  • CIEXYZ
  • CIEXYZTRIPLE
  • ICM Color Structures
  • COLORMATCHSETUP
  • ENUMTYPE
  • LOGCOLORSPACE
  • NAMED_PROFILE_INFO
  • PROFILE
  • PROFILEHEADER


CIEXYZ

The CIEXYZ structure contains the x, y, and z coordinates of a specific color in a specified color space.

typedef struct tagCIEXYZ
{
    FXPT2DOT30 ciexyzX;
    FXPT2DOT30 ciexyzY;
    FXPT2DOT30 ciexyzZ;
} CIEXYZ;
typedef CIEXYZ FAR* LPCIEXYZ;

Members

ciexyzX
x coordinate in fix point (2.30).
ciexyzY
y coordinate in fix point (2.30).
ciexyzZ
z coordinate in fix point (2.30).

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.

See Also

Color Management Overview, ICM 2.0 Structures


CIEXYZTRIPLE

The CIEXYZTRIPLE structure contains the x, y, and z coordinates of the three colors that correspond to the red, green, and blue endpoints for a specified logical color space.

typedef struct tagCIEXYZTRIPLE
{
    CIEXYZ  ciexyzRed;
    CIEXYZ  ciexyzGreen;
    CIEXYZ  ciexyzBlue;
} CIEXYZTRIPLE;
typedef CIEXYZTRIPLE FAR* LPCIEXYZTRIPLE;

Members

ciexyzRed
The xyz coordinates of red endpoint.
ciexyzGreen
The xyz coordinates of green endpoint.
ciexyzBlue
The xyz coordinates of blue endpoint.

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.

See Also

Color Management Overview, ICM 2.0 Structures


ICM Color Structures

This group of structures is used to specify colors for translation.

The GRAYCOLOR Structure

struct GRAYCOLOR {
    WORD    gray;
};

The RGBCOLOR Structure

struct RGBCOLOR {
    WORD    red;
    WORD    green;
    WORD    blue;
};

The CMYKCOLOR Structure

struct CMYKCOLOR {
    WORD    cyan;
    WORD    magenta;
    WORD    yellow;
    WORD    black;
};

The XYZCOLOR Structure

struct XYZCOLOR {
    WORD    X;
    WORD    Y;
    WORD    Z;
};

The YxyCOLOR Structure

struct YxyCOLOR {
    WORD    Y;
    WORD    x;
    WORD    y;
};

The L*a*bCOLOR Structure

struct LabCOLOR {
    WORD    L;
    WORD    a;
    WORD    b;
};

The GENERIC3CHANNEL Structure

struct GENERIC3CHANNEL {
    WORD    ch1;
    WORD    ch2;
    WORD    ch3;
};

The NAMEDCOLOR Structure

struct NAMEDCOLOR {
    DWORD   dwIndex;
};

The HiFiCOLOR Structure

struct HiFiCOLOR {
    BYTE    channel[MAX_COLOR_CHANNELS];
};

The COLOR Structure

typedef union tagCOLOR {
    struct GRAYCOLOR        gray;
    struct RGBCOLOR         rgb;
    struct CMYKCOLOR        cmyk;
    struct XYZCOLOR         XYZ;
    struct YxyCOLOR         Yxy;
    struct LabCOLOR         Lab;
    struct GENERIC3CHANNEL  gen3ch;
    struct NAMEDCOLOR       named;
    struct HiFiCOLOR        hifi;
} COLOR;

A variable of type COLOR may be accessed as any of the supported color space colors by accessing the appropriate member of the union. For instance, given the following variable declaration

COLOR aColor;

The red, green and blue values could be set in the following manner:

aColor.rgb.red=100;
aColor.rgb.green=50;
aColor.rgb.blue=2;

See Also

Color Management Overview, ICM 2.0 Structures


COLORMATCHSETUP

The COLORMATCHSETUP structure contains information that the SetupColorMatching function uses to initialize the Color Management dialog box. After the user closes the dialog box, SetupColorMatching returns information about the user's selection in this structure.

Structure

typedef struct _tagCOLORMATCHSETUP {
    DWORD   dwSize;
    DWORD   dwVersion;
    DWORD   dwFlags;
    HWND    hwndOwner;
    PCTSTR  pSourceName;
    PCTSTR  pDisplayName;
    PCTSTR  pPrinterName;
    DWORD   dwRenderIntent;
    DWORD   dwProofingIntent;
    PTSTR   pMonitorProfile;
    DWORD   ccMonitorProfile;
    PTSTR   pPrinterProfile;
    DWORD   ccPrinterProfile;
    PTSTR   pTargetProfile;
    DWORD   ccTargetProfile;
    DLGPROC lpfnHook;
    LPARAM  lParam;
    PCMSCALLBACKA lpfnApplyCallback;
    LPARAM        lParamApplyCallback;

} COLORMATCHSETUP;

Members

dwSize
Size of the structure. Should be set to sizeof(COLORMATCHSETUP).
dwVersion
Version of the COLORMATCHSETUP structure. This should be set to COLOR_MATCH_VERSION.
dwFlags
A set of bit flags used to initialize the dialog box. If set to 0 on entry, all controls assume their default states.

When the dialog box returns, these flags are set to indicate the user's input.

This member can be set using a combination of the following flags.
Flag | Meaning
CMS_DISABLEICM | If set on entry, this flag indicates that the "Enable Color Management" check box is cleared, disabling all other controls. If set on exit, it means that the user does not wish color management performed.
CMS_ENABLEPROOFING | If set on entry, this flag indicates that the Proofing controls are to be enabled, and the Proofing check box is checked. If set on exit, it means that the user wishes to do color management for a different target device than the selected printer.
CMS_SETRENDERINTENT | If set on entry, this flag indicates that the dwRenderIntent member contains the value to use to initialize the Rendering Intent control. Otherwise, the control defaults to Perceptual rendering. This flag is set on exit if ICM is enabled.
CMS_SETPROOFINTENT | Ignored unless CMS_ENABLEPROOFING is also set. If set on entry, and CMS_ENABLEPROOFING is also set, this flag indicates that the dwProofingIntent member is to be used to initialize the Target Rendering Intent control. Otherwise, the control defaults to Perceptual rendering. This flag is set on exit if proofing is enabled.
CMS_SETMONITORPROFILE | If set on entry, this flag indicates that the color management profile named in the pMonitorProfile member is to be the initial selection in the monitor profile control. If the specified profile is not associated with the monitor, this flag is ignored, and the default profile for the monitor is used.
CMS_SETPRINTERPROFILE | If set on entry, this flag indicates that the color management profile named in the pPrinterProfile member is to be the initial selection in the printer profile control. If the specified profile is not associated with the printer, this flag is ignored, and the default profile for the printer is used.
CMS_SETTARGETPROFILE | If set on entry, this flag indicates that the color profile named in the pTargetProfile member is to be the initial selection in the target profile control. If the specified profile is not installed, this flag is ignored, and the default profile for the printer is used. If the printer has no default profile, then the first profile in alphabetical order will be displayed.
CMS_USEHOOK | This flag specifies that the lpfnHook member contains the address of a hook procedure, and the lParam member contains a value to be passed to the hook procedure when the WM_INITDIALOG message is sent.
CMS_MONITOROVERFLOW | This flag is set on exit if color management is to be enabled and the buffer size given in ccMonitorProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.
CMS_PRINTERROVERFLOW | This flag is set on exit if color management is to be enabled and the buffer size given in ccPrinterProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.
CMS_TARGETOVERFLOW | This flag is set on exit if proofing is to be enabled and the buffer size given in ccTargetProfile is insufficient for the selected profile name. GetLastError returns ERROR_INSUFFICIENT_BUFFER in such a case.
CMS_USEAPPLYCALLBACK | If set on entry, this flag indicates that the SetupColorMatching function should call the function ApplyCallbackFunction. The address of the callback function is contained in lpfnApplyCallback.

hwndOwner
The window handle for the owner of the dialog box, or NULL if the dialog box has no owner.
pSourceName
Pointer to an application-specified string which describes the source profile of the item for which color management is to be performed. If this is NULL, the Image Source control displays the name of the Windows default color profile.
pDisplayName
Points to a string naming the monitor to be used for color management. If this is not the name of a valid monitor, the first enumerated monitor is used.
pPrinterName
Points to a string naming the printer on which the image is to be rendered. If this is not a valid printer name, the default printer is used and named in the dialog.
dwRenderIntent
The type of color management desired. Valid values are:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

dwProofingIntent
The type of color management desired for the proofed image. Valid values are:
INTENT_PERCEPTUAL
INTENT_SATURATION
INTENT_RELATIVE_COLORIMETRIC
INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

pMonitorProfile
Pointer to a buffer in which to place the name of the user-selected monitor profile. If the CMS_SETMONITORPROFILE flag is used, this flag can also be used to select a profile other than the monitor default when the dialog is first displayed.
ccMonitorProfile
The size of the buffer pointed to by the pMonitorProfile member, in characters. If the buffer is not large enough to hold the selected name, the name is truncated to this size, and ERROR_INSUFFICIENT_BUFFER is returned. A buffer of MAX_PATH size always works.
pPrinterProfile
Points to a buffer in which to place the name of the user-selected printer profile. If the CMS_SETPRINTERPROFILE flag is used, this flag can also be used to select a profile other than the printer default when the dialog is first displayed.
ccPrinterProfile
The size of the buffer pointed to by the pPrinterProfile member, in characters. If the buffer is not large enough to hold the selected name, the name is truncated to this size, and ERROR_INSUFFICIENT_BUFFER is returned. A buffer of MAX_PATH size always works.
pTargetProfile
Points to a buffer in which to place the name of the user-selected target profile for proofing. If the CMS_SETTARGETPROFILE flag is used, this flag can also be used to select a profile other than the printer default when the dialog is first displayed.
ccTargetProfile
The size of the buffer pointed to by the pTargetProfile member, in characters. If the buffer is not large enough to hold the selected name, the name is truncated to this size, and ERROR_INSUFFICIENT_BUFFER is returned. A buffer of MAX_PATH size always works.
lpfnHook
If the CMS_USEHOOK flag is set, this member is the address of a dialog procedure (see DialogProc) that can filter or handle messages for the dialog. The hook procedure receives no messages issued before WM_INITDIALOG. It is called on the WM_INITDIALOG message after the system-provided dialog procedure has processed the message. On all other messages, the hook procedure receives the message before the system-provided procedure. If the hook procedure returns TRUE to these messages, the system-provided procedure is not called.

The hook procedure may call the EndDialog function.

lParam
If the CMS_USEHOOK flag is set, this member is passed to the application-provided hook procedure as the lParam parameter when the WM_INITDIALOG message is processed.
lpfnApplyCallback
Contains a pointer to a callback function that is invoked when the Apply button of the Color Management dialog box is selected. If no callback function is provided, this member should be set to NULL.
lParamApplyCallback
Contains a value that will be passed to the function ApplyCallbackFunction through its lParam parameter. The meaning and content of the value is specified by the application.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

A Common Dialog for Color Management, DialogProc, EndDialog


ENUMTYPE

The ENUMTYPE structure contains information that defines the profile enumeration constraints.

typedef struct tagENUMTYPE {
    DWORD   dwSize;
    DWORD   dwVersion;
    DWORD   dwFields;
    PCTSTR  pDeviceName;
    DWORD   dwMediaType;
    DWORD   dwDitheringMode;
    DWORD   dwResolution[2];
    DWORD   dwCMMType;
    DWORD   dwClass;
    DWORD   dwDataColorSpace;
    DWORD   dwConnectionSpace;
    DWORD   dwSignature;
    DWORD   dwPlatform;
    DWORD   dwProfileFlags;
    DWORD   dwManufacturer;
    DWORD   dwModel;
    DWORD   dwAttributes[2];
    DWORD   dwRenderingIntent;
    DWORD   dwCreator;
    DWORD   dwDeviceClass;
} ENUMTYPE, *PENUMTYPE, *LPENUMTYPE;

Members

dwSize
The size of this structure in bytes.
dwVersion
The version number of the ENUMTYPE structure. Should me set to ENUM_TYPE_VERSION.
dwFields
Indicates which fields in this structure are being used. Can be set to any combination of the following values.
Constant
ET_DEVICENAME
ET_MEDIATYPE
ET_DITHERMODE
ET_RESOLUTION
ET_CMMTYPE
ET_CLASS
ET_DATACOLORSPACE
ET_CONNECTIONSPACE
ET_SIGNATURE
ET_PLATFORM
ET_PROFILEFLAGS
ET_MANUFACTURER
ET_MODEL
ET_ATTRIBUTES
ET_RENDERINGINTENT
ET_CREATOR
ET_DEVICECLASS

pDeviceName
User friendly name of the device.
dwMediaType
Indicates which type of media is associated with the profile, such as a printer or screen.
dwDitheringMode
Indicates the style of dithering that will be used when an image is displayed.
dwResolution
The horizontal (x) and vertical (y) resolution in pixels of the device on which the image will be displayed. The x resolution is stored in dwResolution[0], and the y resolution is kept in dwResolution[1].
dwCMMType
The identification number of the CMM that is used in the profile. Identification numbers are registered with the ICC.
dwClass
Indicates the profile class. For a description of profile classes, see Using Device Profiles with ICM. A profile class may have any of the following values.
Profile Class | Signature
Input Device Profile | CLASS_SCANNER
Display Device Profile | CLASS_MONITOR
Output Device Profile | CLASS_PRINTER
Device Link Profile | CLASS_LINK
Color Space Conversion Profile | CLASS_COLORSPAC
Abstract Profile | CLASS_ABSTRACT
Named Color Profile | CLASS_NAMED

dwDataColorSpace
A signature value that indicates the color space in which the profile data is defined. Can be any of the following values.
Profile Class | Signature
XYZ | SPACE_XYZ
Lab | SPACE_Lab
Luv | SPACE_Luv
YCbCr | SPACE_YCbCr
Yxy | SPACE_Yxy
RGB | SPACE_RGB
Grayscale | SPACE_GRAY
HSV | SPACE_HSV
HLS | SPACE_HLS
CMYK | SPACE_CMYK
CMY | SPACE_CMY

dwConnectionSpace
A signature value that indicates the color space in which the profile connection space (PCS) is defined. Can be any of the following values.
Profile Class | Signature
XYZ | SPACE_XYZ
Lab | SPACE_Lab

When the dwClass member is set to CLASS_LINK, the PCS is taken from the dwDataColorSpace member.

dwSignature
Reserved for internal use.
dwPlatform
The primary platform for which the profile was created. The member can be set to any of the following values.
Platform | Value
Apple Computer, Inc. | 'APPL'
Microsoft Corp. | 'MSFT'
Silicon Graphics, Inc. | 'SGI'
Sun Microsystems, Inc. | 'SUNW'
Taligent | 'TGNT'

dwProfileFlags
Bit flags containing hints that the CMM uses to interpret the profile data and can be set to one of the following values.
Constant Meaning
FLAG_EMBEDDEDPROFILE
The profile is embedded in a bitmap file.
FLAG_DEPENDENTONDATA
The profile can't be used independently of the embedded color data. Used for profiles that are embedded in bitmap files.

dwManufacturer
The identification number of the device profile manufacturer. All manufacturer identification numbers are registered with the ICC.
dwModel
The device manufacturer's device model number. All model identification numbers are registered with the ICC.
dwAttributes
Attributes of profile that can be any of the following values.
Constant Meaning
ATTRIB_TRANSPARENCY
Turns transparency on. If this flag is not used, the attribute is reflective by default.
ATTRIB_MATTE
Turns matte display on. If this flag is not used, the attribute is glossy by default.

dwRenderingIntent
The profile rendering intent that can be set to one of the following values:

INTENT_PERCEPTUAL

INTENT_SATURATION

INTENT_RELATIVE_COLORIMETRIC

INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

dwCreator
Signature of the software that created the profile. Signatures are registered with the ICC.
dwDeviceClass
Indicates the device class. A device class may have one of the following values:
Profile Class | Signature
Input Device Profile | CLASS_SCANNER
Display Device Profile | CLASS_MONITOR
Output Device Profile | CLASS_PRINTER

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

Other Color Management Information Sources, Using Device Profiles with ICM, Rendering Intents


LOGCOLORSPACE

The LOGCOLORSPACE structure contains information that defines a logical color space.

typedef struct tagLOGCOLORSPACE {
    DWORD         lcsSignature;
    DWORD         lcsVersion;
    DWORD         lcsSize;
    LCSCSTYPE     lcsCSType;
    LCSGAMUTMATCH lcsIntent;
    CIEXYZTRIPLE  lcsEndpoints;
    DWORD         lcsGammaRed;
    DWORD         lcsGammaGreen;
    DWORD         lcsGammaBlue;
    TCHAR         lcsFilename[MAX_PATH];
} LOGCOLORSPACE, *LPLOGCOLORSPACE;

Members

lcsSignature
Color space signature. At present, this member should always be set to LCS_SIGNATURE.
lcsVersion
Version number; must be 0x400.
lcsSize
Size of this structure, in bytes.
lcsCSType
Color space type. The member can be one of the following values.
Value | Meaning
LCS_CALIBRATED_RGB | Color values are calibrated RGB values. The values are translated using the endpoints specified by the lcsEndpoints member before being passed to the device.
LCS_sRGB | Color values are values are sRGB values.
LCS_WINDOWS_COLOR_SPACE | Color values are Windows default color space color values.

If LCS_CALIBRATED_RGB is not specified, the lcsEndpoints member is ignored.

lcsIntent
The gamut mapping method. This member can be one of the following values.
Value | Meaning
LCS_GM_ABS_COLORIMETRIC | Maintain the white point. Match the colors to their nearest color in the destination gamut.
LCS_GM_BUSINESS | Maintain saturation. Used for business charts and other situations in which undithered colors are required.
LCS_GM_GRAPHICS | Maintain colorimetric match. Used for graphic designs and named colors.
LCS_GM_IMAGES | Maintain contrast. Used for photographs and natural images.

These gamut mapping methods provide a one-to-one correspondence with the rendering intents defined in the ICC Profile Format Specification version 3.3. The LCS_GM_ABS_COLORIMETRIC method is equivalent to an absolute colorimetric rendering intent. LCS_GM_BUSINESS corresponds to a saturated rendering intent. LCS_GM_GRAPHICS is relative colorimetric intent. LCS_GM_IMAGES is perceptual rendering intent.

lcsEndpoints
Red, green, blue endpoints.
lcsGammaRed
Scale of the red coordinate.
lcsGammaGreen
Scale of the green coordinate.
lcsGammaBlue
Scale of the blue coordinate.
lcsFilename
A null-terminated string that names a color profile file. This member is typically set to zero, but may be used to set the color space to be exactly as specified by the color profile. This is useful for devices that input color values for a specific printer, or when using an installable image color matcher. If a color profile is specified, all other members of this structure should be set to reasonable values, even if the values are not completely accurate.

Remarks

If the lcsCSType member is set to LCS_sRGB or LCS_WINDOWS_COLOR_SPACE, the other members of this structure are ignored, and ICM uses the sRGB color space. The lcsEndpoints, lcsGammaRed, lcsGammaGreen, and lcsGammaBlue members are used to describe the logical color space. The lcsEndpoints member is a CIEXYZTRIPLE that contains the x, y, and z values of the color space's RGB endpoint.

Whenever the lcsFilename member contains a file name and the lcsCSType member is set to LCS_CALIBRATED_RGB, ICM ignores the other members of this structure. It uses the color space in the file as the color space to which this LOGCOLORSPACE structure refers.

The relation between tri-stimulus values X,Y,Z and chromaticity values x,y,z is as follows

x = X/(X+Y+Z)

y = Y/(X+Y+Z)

z = Z/(X+Y+Z)

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.
Unicode: Defined as Unicode and ANSI structures.

See Also

RGB, CMYK, BITMAPV4HEADER, BITMAPV5HEADER


NAMED_PROFILE_INFO

The NAMED_PROFILE_INFO structure is used to store information about a named color profile.

typedef struct tagNAMED_PROFILE_INFO{
    DWORD        dwFlags;
    DWORD        dwCount;
    DWORD        dwCountDevCoordinates;
    COLOR_NAME    szPrefix;
    COLOR_NAME    szSuffix;
}NAMED_PROFILE_INFO;

Members

dwFlags
Specifies flags to used control creation of the transform. These flags are intended only as hints, and it is up to the CMM to determine how best to use these flags.

Set the high-order WORD to ENABLE_GAMUT_CHECKING if the transform will be used for gamut checking.

The low-order WORD can have one of the following constant values: PROOF_MODE, NORMAL_MODE, BEST_MODE. Moving from PROOF_MODE to BEST_MODE, output quality generally improves and transform speed declines.

dwCount
Total number of named colors in the profile.
dwCountDevCoordinates
Total number of device coordinates for each named color.
szPrefix
Pointer to a string containing the prefix for each color name.
szSuffix
Pointer to a string containing the suffix for each color name.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.


PROFILE

The PROFILE structure contains information that defines a color profile. See Using Device Profiles with ICM for more information.

typedef struct tagPROFILE {
    DWORD   dwType;
    PVOID   pProfileData;
    DWORD   cbDataSize;
} PROFILE;

Members

dwType
Must be set to one of the following values.
Value Meaning
PROFILE_FILENAME
Indicates that the pProfileData member contains a null-terminated string that holds the name of a device profile file.
PROFILE_MEMBUFFER
Indicates that the pProfileData member contains a pointer to a device profile in a memory buffer.

pProfileData
The contents of this member is indicated by the dwTYPE member. It will either be a pointer to a null-terminated string containing the file name of the device profile, or it will be a pointer to a buffer in memory containing the device profile data.
cbDataSize
The size in bytes of the data buffer pointed to by the pProfileData member.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.

See Also

Using Device Profiles with ICM


PROFILEHEADER

The PROFILEHEADER structure contains information that describes the contents of a device profile file. This header occurs at the beginning of a device profile file.

typedef struct tagPROFILEHEADER {
    DWORD   phSize;
    DWORD   phCMMType;
    DWORD   phVersion;
    DWORD   phClass;
    DWORD   phDataColorSpace;
    DWORD   phConnectionSpace;
    DWORD   phDateTime[3];
    DWORD   phSignature;
    DWORD   phPlatform;
    DWORD   phProfileFlags;
    DWORD   phManufacturer;
    DWORD   phModel;
    DWORD   phAttributes[2];
    DWORD   phRenderingIntent;
    CIEXYZ  phIlluminant;
    DWORD   phCreator;
    BYTE    phReserved[44];
} PROFILEHEADER;

Members

phSize
The size of the profile in bytes.
phCMMType
The identification number of the CMM that is used in the profile. Identification numbers are registered with the ICC.
phVersion
The version number of the profile. The version number is determined by the ICC. The current major version number is 02h. The current minor version number is 10h. The major and minor version numbers are in binary coded decimal (BCD). They must be stored in the following format.
Byte Number | Contents
0 | Major version number in BCD.
1 | Minor version number in the most significant nibble of this byte. Bug fix version number in the least significant nibble.
2 | Reserved. Must be set to 0.
3 | Reserved. Must be set to 0.

phClass
Indicates the profile class. For a description of profile classes, see Using Device Profiles with ICM. A profile class may have any of the following values.
Profile Class | Signature
Input Device Profile | CLASS_SCANNER
Display Device Profile | CLASS_MONITOR
Output Device Profile | CLASS_PRINTER
Device Link Profile | CLASS_LINK
Color Space Conversion Profile | CLASS_COLORSPAC
Abstract Profile | CLASS_ABSTRACT
Named Color Profile | CLASS_NAMED

phDataColorSpace
A signature value that indicates the color space in which the profile data is defined. The member can be any of the following values.
Profile Class | Signature
XYZ | SPACE_XYZ
Lab | SPACE_Lab
Luv | SPACE_Luv
YCbCr | SPACE_YCbCr
Yxy | SPACE_Yxy
RGB | SPACE_RGB
Grayscale | SPACE_GRAY
HSV | SPACE_HSV
HLS | SPACE_HLS
CMYK | SPACE_CMYK
CMY | SPACE_CMY

phConnectionSpace
A signature value that indicates the color space in which the profile connection space (PCS) is defined. The member can be any of the following values.
Profile Class | Signature
XYZ | SPACE_XYZ
Lab | SPACE_Lab

When the phClass member is set to CLASS_LINK, the PCS is taken from the phDataColorSpace member.

phDateTime
The data and time that the profile was created.
phSignature
Reserved for internal use.
phPlatform
The primary platform for which the profile was created. The primary platform can be set to any of the following values.
Platform | Value
Apple Computer, Inc. | 'APPL'
Microsoft Corp. | 'MSFT'
Silicon Graphics, Inc. | 'SGI'
Sun Microsystems, Inc. | 'SUNW'
Taligent | 'TGNT'

phProfileFlags
Bit flags containing hints that the CMM uses to interpret the profile data. The member can be set to the following values.
Constant Meaning
FLAG_EMBEDDEDPROFILE
The profile is embedded in a bitmap file.
FLAG_DEPENDENTONDATA
The profile can't be used independently of the embedded color data. Used for profiles that are embedded in bitmap files.

phManufacturer
The identification number of the device profile manufacturer. All manufacturer identification numbers are registered with the ICC.
phModel
The device manufacturer's device model number. All model identification numbers are registered with the ICC.
phAttributes
Attributes of profile. The profile attributes can be any of the following values.
Constant Meaning
ATTRIB_TRANSPARENCY
Turns transparency on. If this flag is not used, the attribute is reflective by default.
ATTRIB_MATTE
Turns matte display on. If this flag is not used, the attribute is glossy by default.

phRenderingIntent
The profile rendering intent. The member can be set to one of the following values.

INTENT_PERCEPTUAL

INTENT_SATURATION

INTENT_RELATIVE_COLORIMETRIC

INTENT_ABSOLUTE_COLORIMETRIC

For more information, see Rendering Intents.

phIlluminant
Profile illuminant.
phCreator
Signature of the software that created the profile. Signatures are registered with the ICC.
phReserved
Reserved for future use.

QuickInfo

Windows NT: Requires version 5.0 or later.
Windows: Requires Windows 98.
Windows CE: Unsupported.
Header: Declared in icm.h.

See Also

Other Color Management Information Sources, Using Device Profiles with ICM, Rendering Intents


Macros for CMYK Values and Colors

The following macros are useful in manipulating CMYK values.

Macro | Description
CMYK | Builds a CMYK value from individual cyan, magenta, yellow, and black values.
GetCValue | Retrieves the cyan color value from a CMYK color value.
GetKValue | Retrieves the black color value from a CMYK color value.
GetMValue | Retrieves the magenta value from a CMYK color value.
GetYValue | Retrieves the yellow color value from a CMYK color value.

The following macros are used with color.

Macro | Description
GetBValue | Gets an RGB blue value.
GetGValue | Gets an RGB green value.
GetRValue | Gets an RGB red value.
PALETTEINDEX | Accepts an index to a logical-color palette entry and returns a palette-entry specifier.
PALETTERGB | Accepts three values that represent the relative intensities of red, green, and blue and returns a palette-relative red, green, blue (RGB) specifier.
RGB | Selects a red, green, blue (RGB) color based on the arguments supplied and the color capabilities of the output device.


CMYK

The CMYK macro creates a CMYK color value by combining the specified cyan, magenta, yellow, and black values.

COLORREF CMYK(
  c,
  m,
  y,
  k
);

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.

See Also

Color Management Overview, Macros for CMYK Values and Colors, GetCValue, GetMValue, GetKValue, GetYValue


GetCValue

The GetCValue macro retrieves the cyan color value from a CMYK color value.

BYTE GetCValue(
  cmyk
);

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.

See Also

Color Management Overview, Macros for CMYK Values and Colors, CMYK, GetKValue, GetMValue, GetYValue


GetKValue

The GetKValue macro retrieves the black color value from a CMYK color value.

BYTE GetKValue(
  cmyk
);

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.

See Also

Color Management Overview, Macros for CMYK Values and Colors, CMYK, GetCValue, GetMValue, GetYValue


GetMValue

The GetMValue macro retrieves the magenta color value from a CMYK color value.

BYTE GetMValue
  cmyk
);

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.

See Also

Color Management Overview, Macros for CMYK Values and Colors, CMYK, GetCValue, GetKValue, GetYValue


GetYValue

The GetYValue macro retrieves the yellow color value from a CMYK color value.

BYTE GetYValue(
  cmyk
);

QuickInfo

Windows NT: Requires version 4.0 or later.
Windows: Requires Windows 95 or later.
Windows CE: Unsupported.
Header: Declared in wingdi.h.

See Also

Color Management Overview, Macros for CMYK Values and Colors, CMYK, GetCValue, GetMValue, GetKValue


Common Color Messages

The following messages are used with color.

WM_PALETTECHANGED

WM_PALETTEISCHANGING

WM_QUERYNEWPALETTE

WM_SYSCOLORCHANGE


Error Codes Specific To ICM

The following is a list of error codes that are specifically related to the use of ICM 2.0. This does not mean that ICM functions will return only these error codes. It means that the codes in the table below are returned only by ICM functions. They may also return other Win32 error codes that are documented elsewhere in the Win32 API of the Platform SDK.

ERROR_DELETING_ICM_XFORM
The specified color transform could not be deleted.
ERROR_DUPLICATE_TAG
The specified color profile element tag is already present in the color profile.
ERROR_ICM_NOT_ENABLED
Image Color Management is not currently enabled.
ERROR_INVALID_CMM
The specified file name does not refer to a valid color management module.
ERROR_INVALID_COLORSPACE
The specified color space is invalid.
ERROR_INVALID_PROFILE
The specified file name does not refer to a valid color profile.
ERROR_INVALID_TRANSFORM
The color transform that was specified is not a valid color transform.
ERROR_PROFILE_NOT_ASSOCIATED_WITH_DEVICE
The specified color profile is not associated with any device.
ERROR_PROFILE_NOT_FOUND
The specified color profile file name was not found. The file name or path is incorrect.
ERROR_TAG_NOT_FOUND
The specified color profile element tag was not found in the color profile.
ERROR_TAG_NOT_PRESENT
A color profile element tag that is required for the function to succeed was not passed to the function.


ICM 2.0 Glossary

A B C D G H L P R S T W


A

additive primary colors
Colors that can be added to black to mix a new color. The additive primary colors are red, green, and blue.


B

brightness
The brightness of a color refers to the intensity of light that is reflected or transmitted by an image.


C

CMYK
The Cyan, Magenta, Yellow, and blacK color space. It is often implemented on printers.
color channel
A component of a color space. For instance, an RGB color space has red, green, and blue color channels.
color conversion
The process of converting colors from one color space to another.
Color Management Module (CMM)
A code module that uses device profiles to do color conversion and color mapping.
color mapping
See color matching.
color matching
Matching a converted color to its visually closest color in the destination color space.
color model
See color space.
color space
A mapping of color components onto a Cartesian coordinate system in three or more dimensions.


D

DAC
Digital to analog converter.
device link profile
A file that contains a concatenation of color conversions that are used often.
device profile
A file that contains information on how to convert colors from the gamut of a device into the PCS. It also holds the information necessary for conversion of colors from the PCS into the device's gamut.


G

gamma correction
When color is produced on an electronic device, the eye perceives it differently than if it was printed on paper. The gamma correction factor compensates for that perceived difference.
gamma curve
A collection of gamma corrections over the entire range of colors. When plotted on a graph, they form a curve.
gamma ramp
See gamma curve .
gamut
The set of colors from a color space that a device can produce.


H

hard proofing
Previewing or proofing an image by printing a hard copy of it.
HLS
A color space often used by artists. Its components are Hue, Lightness, and Saturation.
HSV
A color space often used by artists. Its components are Hue, Saturation, and Value.
hue
A pure color. A hue is a specific position on the visible portion of the electromagnetic spectrum.


L

lightness
One color channel in the HLS color space. It is a measure of the brightness or darkness of the color. Increasing lightness produces tints of a hue. Decreasing lightness produces shades of a hue.


P

primary colors
The three essential colors in a color space that can be mixed to produce all other colors.
Profile Connection Space (PCS)
A device independent color space used for color conversions and color matching.


R

rendering intent
Approaches to rendering color from one color space to another. The rendering intents used in ICM are defined by the International Color Consortium (ICC).
RGB
The Red, Green, and Blue color space.
RGB Triple
A quantity that contains RGB color space values.


S

saturation
Generally saturation is the amount of gray that is mixed into a hue. Zero saturation produces a shade of gray. Full saturation produces a pure hue.
shade
A shade of a color is made by adding black to its hue.
soft proofing
Previewing or proofing an image on a video display.
sRGB
A standardized RGB color space proposed by Microsoft and Hewlett-Packard that is device independent.
subtractive primary colors
Colors that can be subtracted from white to mix a new color. The subtractive primary colors are cyan, yellow, and magenta.


T

tint
A tint of a color is created by mixing a hue with white.
tone
A tone of a color is obtained by mixing its hue with gray.


W

white point
The whitest white that can be produced in a device's color gamut.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.