Chromium color management

Create a color space object from an ICC profile. This request returns a zcr_color_space_creator_v1 object which either returns an error or the successfully created zcr_color_space_v1 object.

The description of the color space to create is sent in the form of an ICC profile as a file descriptor in the argument icc.

The fd must be seekable and the maximum size of the ICC profile is 4 MB. Violating these requirements will raise an icc_fd protocol error. A compositor must not modify the contents of the file, and the fd may be sealed for writes and size changes.

The file contents must represent a valid ICC profile. The ICC profile version must be 2 or 4, it must be a 3 channel profile and the class must be 'input', 'output', 'abstract' or 'display'. Violating these requirements will not result in a protocol error but raise the zcr_color_space_creator_v1.error event.

See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for more details about the created object.

See the specification from International Color Consortium for more details about ICC profiles, also known as ISO 15076-1:2010.

[Deprecated] Create a color space object from well-known names. This request returns a zcr_color_space_creator_v1 object which either returns an error or the successfully created zcr_color_space_v1 object.

EOTF, chromaticity and whitepoint must not be unknown. Otherwise, or if a given value is not listed in the enumeration, the protocol error bad_enum is raised.

See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for more details about the created object. Use create_color_space_from_complete_names instead.

[Deprecated] Create a color space object from parameters. This request returns a zcr_color_space_creator_v1 object which either returns an error or the successfully created zcr_color_space_v1 object.

EOTF must not be unknown. Otherwise, or if a given EOTF is not listed in the enumeration, the protocol error bad_enum is raised.

The white point must be inside the triangle created by the red, green and blue primaries. Otherwise the bad_param protocol error is raised.

All the chromaticity values are multiplied by 10000 to produce the integers carried by the protocol.

See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for more details about the created object. Use create_color_space_from_complete_params instead.

This creates a new zcr_color_management_output_v1 object for the given wl_output.

See the zcr_color_management_output_v1 interface for more details.

This creates a new color zcr_color_management_surface_v1 object for the given wl_surface.

See the zcr_color_management_surface_v1 interface for more details.

Destroy the zcr_color_manager_v1 object. This does not affect any other objects in any way.

Create a color space object from well-known names. This request returns a zcr_color_space_creator_v1 object which either returns an error or the successfully created zcr_color_space_v1 object.

EOTF, chromaticity and whitepoint must not be unknown. Otherwise, or if a given value is not listed in the enumeration, the protocol error bad_enum is raised.

This request additionally includes matrix and range information.

See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for more details about the created object.

Create a color space object from parameters. This request returns a zcr_color_space_creator_v1 object which either returns an error or the successfully created zcr_color_space_v1 object.

EOTF must not be unknown. Otherwise, or if a given EOTF is not listed in the enumeration, the protocol error bad_enum is raised.

The white point must be inside the triangle created by the red, green and blue primaries. Otherwise the bad_param protocol error is raised.

All the chromaticity values are multiplied by 10000 to produce the integers carried by the protocol.

This request additionally includes matrix and range information.

See the zcr_color_space_v1 and zcr_color_space_creator_v1 interface for more details about the created object.

Names that describe a well-known EOTF.

A compositor must support all of these based on the protocol interface version.

Names that describe well-known chromaticities.

A compositor must support all of these based on the protocol interface version.

Names that describe well-known whitepoints.

A compositor must support all of these based on the protocol interface version.

Names that describe typical ColorSpace Matrix IDs

Names that describe typical RGB value ranges.

This creates a new zcr_color_space_v1 object for the current color space of the output. There always is exactly one color space active for an output so the client should destroy the color space created by earlier invocations of this request. This request is usually sent as a reaction to the color_space_changed event or when creating a zcr_color_management_output_v1 object.

The created zcr_color_space_v1 object preserves the color space of the output from the time the object was created.

The resulting color space object allows get_information request.

See the zcr_color_space_v1 interface for more details.

Destroy the color zcr_color_management_output_v1 object. This does not affect any remaining protocol objects.

The color_space_changed event is sent whenever the color space of the output changed, followed by one wl_output.done event common to output events across all extensions.

This is not an initial event.

This is both an initial event and sent whenever the value changed. When the value changed, this event is followed by one wl_output.done event common to output events across all extensions.

The extended dynamic range value describes how much dynamic range is available relative to the SDR maximum white. EDR value is proportional to luminance, and the luminance of black is used as the zero level. A value of 1.0 means that the the display can not display anything brighter than SDR maximum white. A value of 3.0 means that the SDR maximum white is at one third of the highest luminance the display can produce.

The absolute luminance of the SDR maximum white depends on the monitor capabilities, the viewing conditions and the viewer personal preferences. A such, it cannot be given a single value in cd/m². Compositors using HDR video modes should allow users to control the the SDR maximum white level which the output EDR value is calculated from.

The SDR maximum white is a relative reference luminance that allows to tone-map content from different dynamic ranges into a single common dynamic range for display.

The EDR value is multiplied by 1000 to produce the integer value carried by the protocol.

Assuming an alpha channel exists, it is always linear. The alpha mode determines whether the color channels include alpha pre-multiplied or not. Using straight alpha might have performance benefits.

Alpha mode is double buffered, and will be applied at the time wl_surface.commit of the corresponding wl_surface is called.

By default, a surface is assumed to have pre-multiplied alpha.

Set the extended dynamic range (EDR) value for the underlying surface. The EDR value is double buffered, and will be applied at the time wl_surface.commit of the corresponding wl_surface is called.

The EDR value describes how much dynamic range is encoded relative to the SDR maximum white. EDR value is proportional to luminance, using the luminance of black as the zero level. A value of 1.0 means that the SDR maximum white is the highest possible luminance of the surface. A value of 3.0 means that the SDR maximum white is one third of the highest possible luminance of the surface.

The color space attached to the surface can make the code values in the buffer non-linear in regards to the luminance. The code value to produce a third of the luminance of the biggest code value therefore might not be one third of the biggest code value.

For the definition of the SDR maximum white on an output, see zcr_color_management_output_v1.extended_dynamic_range. Content producers are free to choose their SDR maximum white level. How it shall be displayed depends on the monitor capabilities and the output EDR value.

By default the EDR value is 1.0. The compositor will tone map the image to match the EDR of each output the surface is shown on. The aim for the EDR-EDR mapping is to produce a relative luminance mapping that looks equally good regardless of the viewing conditions and the monitor capabilities, assuming the output EDR value was tuned to the output capabilities and the viewing environment. There might be performance and image quality benefits from providing content readily tone mapped to the EDR value of the output the surface is shown on.

The EDR value is multiplied by 1000 to produce the integer value carried by the protocol.

Set the color space of the underlying surface. The color space and render intent are double buffered, and will be applied at the time wl_surface.commit of the corresponding wl_surface is called.

The render intent gives the compositor a hint what to optimize for in color space transformations.

By default, a surface is assumed to have the sRGB color space and an arbitrary render intent.

If the color space of the surface matches the color space of an output it is shown on the performance and color accuracy might improve. To find those color spaces the client can listen to the preferred_color_space or the wl_surface.enter/leave events. This improvement may require using the color space object created by zcr_color_management_output_v1.get_color_space.

This request sets the surface color space to the defaults, see set_color_space. The setting will be applied at the time wl_surface.commit of the corresponding wl_surface is called.

Destroy the zcr_color_management_surface_v1 object.

When the last zcr_color_management_surface_v1 object for a wl_surface is destroyed, the destruction will pend unsetting the wl_surface's color space, render intent and alpha mode similar to set_color_space will pend a set.

The preferred_color_space event is sent when the compositor determines or switches the output that implies the preferred color space. The preferred color space is the one which likely has the most performance and quality benefits if used by a client for its surface contents.

The event does not carry a zcr_color_space_v1 but a wl_output object. The concrete zcr_color_space_v1 can be created by calling zcr_color_management_output_v1.get_color_space on the output and listening to zcr_color_management_output_v1.color_space_changed events.

As clients may bind to the same global wl_output multiple times, this event is sent for each bound instance that matches the preferred color space output. If a client has not bound to the right wl_output global at all, this event is not sent.

This is only a hint and clients can set any valid color space with set_color_space but there might be performance and color accuracy improvements by providing the surface in the preferred color space.

Rendering intent allow the client to hint at how to perform color space transformations.

See the ICC specification for more details about rendering intent.

Specifies whether alpha is pre-multiplied into color channels or not. If pre-multiplied, the linear alpha value is already multiplied with the (non-linear) color channel code values in the color channels.

Delivers the successfully created color space.

The resulting color space object does not allow get_information request.

This event is sent if the color space creation failed.

Bitmask of errors which occured while trying to create a color space

As a reply to this request, the compositor will send all available information events describing this color space object and finally the 'done' event. Other extensions may define more events to be sent before 'done'.

This request is allowed only on zcr_color_space_v1 objects where the message that created the object specifies that get_information is allowed. Otherwise protocol error no_information is raised.

Every get_information request on the same object will always return the exact same data.

See zcr_color_management_output_v1.get_color_space and zcr_color_space_creator_v1.created.

Destroy the zcr_color_space_v1 object.

Destroying the zcr_color_space_v1 which is active on a surface or an output does not change the color space of those objects.

This event may be sent only as a response to zcr_color_space_v1.get_information.

The icc argument provides a file descriptor to the client which can be memory-mapped to provide the ICC profile describing the color space. The fd must be mapped with MAP_PRIVATE and read-only by the client.

Compositors should send this event always when information is requested. ICC profiles provide the common foundation which all color managed clients may rely on.

[Deprecated] This event may be sent only as a response to zcr_color_space_v1.get_information.

EOTF, chromaticity and whitepoint contain well-known names of those properties if available and unknown otherwise.

Compositors should not assume that all clients can understand these names. The names are provided for client convenience. If a client understands the name triplet, it may ignore other information about the color space, the ICC profile for example. Use complete_names instead.

[Deprecated] This event may be sent only as a response to zcr_color_space_v1.get_information.

The RGB primary value arguments along with the whitepoint value arguments and eotf can be used to define an arbitrary or custom color space.

The eotf enum contains well known names of that property, but the compositor should not assume that all clients will understand those names. Use complete_params instead.

This event may be sent only as a response to zcr_color_space_v1.get_information.

This signifies that all color space information events have been delivered for the object.

This event may be sent only as a response to zcr_color_space_v1.get_information.

EOTF, chromaticity, matrix, range and whitepoint contain well-known names of those properties if available and unknown otherwise.

Compositors should not assume that all clients can understand these names. The names are provided for client convenience. If a client understands the name triplet, it may ignore other information about the color space, the ICC profile for example.

This event may be sent only as a response to zcr_color_space_v1.get_information.

The RGB primary value arguments along with the whitepoint value arguments and eotf can be used to define an arbitrary or custom color space.

The eotf enum contains well known names of that property, but the compositor should not assume that all clients will understand those names.