Commit 9466f79b authored by Sebastian Wick's avatar Sebastian Wick
Browse files

color management: protocol fixes and color_space_creator object



* creating a color space now leads through the color_space_creator
  object which allows us to fail at ceating the color space
* there are now three ways to create a color space. From an ICC profile,
  from well-known names and parametrically.
* multiple color_management_outputs can now be created for a single
  wl_output
* color_space_changed is not send when the object is created anymore
* clearify that destroying a color space has no effect on the color
  space state associated with surfaces and outputs
* preferred color space is send only after it is determined or changed
* preferred color space is send to all matching wl_outputs
Signed-off-by: Sebastian Wick's avatarSebastian Wick <sebastian@sebastianwick.net>
parent 4946f7d2
Pipeline #198178 passed with stages
in 36 seconds
......@@ -38,27 +38,38 @@
profiles.
</description>
<enum name="error">
<description summary="fatal color manager errors">
These fatal protocol errors may be emitted in response to illegal color
management requests.
<enum name="eotf_names">
<!-- FIXME How does a client know what server supports? -->
<description summary="well-known EOTF names">
Names that describe a well-known EOTF
</description>
<entry name="invalid_icc_profile" value="0" summary="invalid ICC profile"/>
<entry name="already_exists" value="1" summary="color managed surface/output already exists"/>
<entry name="unknown" value="0" summary="unknown EOTF"/>
<!-- TODO add regularily used EOTFs -->
</enum>
<enum name="color_space_name">
<description summary="well-known color space name">
Names that describe a complete (primaries, white point and EOTF),
well-known color space.
<enum name="chromaticity_names">
<!-- FIXME How does a client know what server supports? -->
<description summary="well-known chromaticity names">
Names that describe well-known chromaticities
</description>
<entry name="none" value="0" summary="the color space doesn't have a well-known name"/>
<!-- TODO add regularily used color spaces -->
<entry name="unknown" value="0" summary="unknown chromaticity"/>
<!-- TODO add regularily used chromaticities -->
</enum>
<request name="create_color_space">
<description summary="create a color space object">
Create a color space object from an ICC profile.
<enum name="whitepoint_names">
<!-- FIXME How does a client know what server supports? -->
<description summary="well-known whitepoint names">
Names that describe well-known whitepoints
</description>
<entry name="unknown" value="0" summary="unknown whitepoint"/>
<!-- TODO add regularily used whitepoints -->
</enum>
<request name="create_color_space_from_icc">
<description summary="create a color space object from ICC profiles">
Create a color space object from an ICC profile. This request returns
a zwp_color_space_creator_v1 object which either returns an error
or the successfully created zwp_color_space_v1 object.
<!-- FIXME what exactly are the restrictions on the fd? In weston I only
check for O_NONBLOCK then continue to read from it and post a wl
......@@ -73,30 +84,60 @@
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'.
If the conditions are not met a protocol error 'invalid_icc_profile' is
raised by the compositor.
If the color space described by the ICC profile has its well-known name
listed in color_space_name, that name can be set in the 'name' argument.
Otherwise 'name' must be set to 'none'.
See the zwp_color_space_v1 interface for more details about the created
object.
See the zwp_color_space_v1 and zwp_color_space_creator_v1 interface for
more details about the created object.
See the ICC specification for more details about ICC profiles.
</description>
<arg name="id" type="new_id" interface="zwp_color_space_v1"/>
<arg name="id" type="new_id" interface="zwp_color_space_creator_v1"/>
<arg name="icc" type="fd"/>
<arg name="name" type="uint" enum="color_space_name"/>
</request>
<request name="create_color_space_from_names">
<description summary="create a color space object from well-known names">
Create a color space object from well-known names. This request returns
a zwp_color_space_creator_v1 object which either returns an error
or the successfully created zwp_color_space_v1 object.
EOTF, chromaticity and whitepoint must not be unknown.
See the zwp_color_space_v1 and zwp_color_space_creator_v1 interface for
more details about the created object.
</description>
<arg name="id" type="new_id" interface="zwp_color_space_creator_v1"/>
<arg name="eotf" type="uint" enum="eotf_names" summary="EOTF"/>
<arg name="chromaticity" type="uint" enum="chromaticity_names" summary="chromaticity"/>
<arg name="whitepoint" type="uint" enum="whitepoint_names" summary="whitepoint"/>
</request>
<request name="create_color_space_from_params">
<description summary="create a color space object from well-known names">
Create a color space object from parameters. This request returns
a zwp_color_space_creator_v1 object which either returns an error
or the successfully created zwp_color_space_v1 object.
EOTF must not be unknown. The white point must be inside the triangle
created by the red, green and blue primaries.
See the zwp_color_space_v1 and zwp_color_space_creator_v1 interface for
more details about the created object.
</description>
<arg name="id" type="new_id" interface="zwp_color_space_creator_v1"/>
<arg name="eotf" type="uint" enum="eotf_names" summary="EOTF"/>
<arg name="primary_r_x" type="uint" summary="red primary X * 10000"/>
<arg name="primary_r_y" type="uint" summary="red primary Y * 10000"/>
<arg name="primary_g_x" type="uint" summary="green primary X * 10000"/>
<arg name="primary_g_y" type="uint" summary="green primary Y * 10000"/>
<arg name="primary_b_x" type="uint" summary="blue primary X * 10000"/>
<arg name="primary_b_y" type="uint" summary="blue primary Y * 10000"/>
<arg name="white_point_x" type="uint" summary="white point X * 10000"/>
<arg name="white_point_y" type="uint" summary="white point Y * 10000"/>
</request>
<request name="get_color_management_output">
<description summary="create a color management output from a wl_output">
This creates a new color zwp_color_management_output_v1 object for the
given wl_output. If get_color_management_output is called with a
wl_output that already has an active zwp_color_management_output_v1
associated with it an error is raised.
This creates a new zwp_color_management_output_v1 object for the
given wl_output.
See the zwp_color_management_output_v1 interface for more details.
</description>
......@@ -136,10 +177,8 @@
<event name="color_space_changed">
<description summary="color space changed">
The color_space_changed event is sent after creating a
zwp_color_management_output_v1 (see
zwp_color_manager_v1.get_color_management_output) and whenever the color
space of the output changed.
The color_space_changed event is sent whenever the color space of the
output changed.
</description>
</event>
......@@ -176,6 +215,7 @@
<enum name="render_intent">
<description summary="render intent">
<!-- FIXME: rendering intent is not just a hint -->
Rendering intent allow the client to hint at how to perform color space
transformations.
......@@ -194,6 +234,7 @@
buffered, and will be applied at the time wl_surface.commit of the
corresponding wl_surface is called.
<!-- FIXME: same problem as in the render_intent enum -->
The render intent gives the compositor a hint what to optimize for in
color space transformations.
......@@ -221,10 +262,8 @@
<event name="preferred_color_space">
<description summary="preferred color space">
The preferred_color_space event is sent after creating an
zwp_color_management_surface_v1 (see
zwp_color_manager_v1.get_color_management_surface) and whenever the
preferred color space changed.
The preferred_color_space event is sent once the preferred color
space is determined or changes.
The event does not carry a zwp_color_space_v1 but a wl_output object.
The concrete zwp_color_space_v1 can be created by calling
......@@ -232,6 +271,11 @@
listening to the zwp_color_management_output_v1.color_space_changed
event.
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.
......@@ -243,12 +287,48 @@
<description summary="destroy the color management surface">
Destroy the zwp_color_management_surface_v1 object.
The surface does not have a color space set after destroying this
object.
When the last zwp_color_management_surface_v1 object for a wl_surface
is destroyed, the destruction will pend unsetting the wl_surface's
color space, similar to set_color_space will pend a set.
</description>
</request>
</interface>
<interface name="zwp_color_space_creator_v1" version="1">
<description summary="color space creator">
A zwp_color_space_creator_v1 object returns a created color space
or the error which occured during creation.
Once a zwp_color_space_creator_v1 object has delivered a 'created'
or 'error' event it is automatically destroyed.
</description>
<enum name="creation_error" bitfield="true">
<description summary="color space creation error">
Bitmask of errors which occured while trying to create a color space
</description>
<entry name="malformed_icc" value="0x1" summary="malformed ICC profile"/>
<entry name="bad_icc" value="0x2" summary="ICC profile does not meet requirements"/>
<entry name="bad_name" value="0x4" summary="names must not be unknown"/>
<entry name="bad_primaries" value="0x8" summary="bad primaries"/>
<entry name="bad_whitepoint" value="0x10" summary="bad whitepoint"/>
</enum>
<event name="created">
<description summary="color space object created">
Sends the successfully created color space.
</description>
<arg name="id" type="new_id" interface="zwp_color_space_v1"/>
</event>
<event name="error">
<description summary="color space creation failed">
This event is send if the color space creation failed.
</description>
<arg name="error" type="uint" enum="creation_error" summary="error bitmask"/>
</event>
</interface>
<interface name="zwp_color_space_v1" version="1">
<description summary="color space">
Describes a color space which can be attached to a surface
......@@ -256,9 +336,9 @@
information like the ICC profile and the well-known name to alow clients
to do color space transformations.
The client can create a zwp_color_space_v1 object from an ICC profile by
calling zwp_color_manager_v1.create_color_space or from an output by
calling zwp_color_management_output_v1.get_color_space.
The client can create a zwp_color_space_v1 object with
zwp_color_manager_v1 requests or from an output by calling
zwp_color_management_output_v1.get_color_space.
</description>
<request name="get_information">
......@@ -276,23 +356,25 @@
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 by the client. Note, that the
fd may not be the same as the fd passed to
zwp_color_manager_v1.create_color_space.
The name argument contains the well-known name of the color space. If
the color space does not have a well-known name the name will be set
to 'none'. The name can be 'none' for any other reason even if this
color space represents one of the well-known color spaces listed in
zwp_color_manager_v1.color_space_name.
fd as well as the contents of the profile may not be the same as the fd
passed to zwp_color_manager_v1.create_color_space.
EOTF, chromaticity and whitepoint contain well-known names of those
properties if available and unknown otherwise.
</description>
<arg name="icc" type="fd" summary="ICC profile file descriptor"/>
<arg name="size" type="uint" summary="ICC profile size, in bytes"/>
<arg name="name" type="uint" enum="zwp_color_manager_v1.color_space_name" summary="well-known name"/>
<arg name="icc_size" type="uint" summary="ICC profile size, in bytes"/>
<arg name="eotf" type="uint" enum="zwp_color_manager_v1.eotf_names" summary="EOTF"/>
<arg name="chromaticity" type="uint" enum="zwp_color_manager_v1.chromaticity_names" summary="chromaticity"/>
<arg name="whitepoint" type="uint" enum="zwp_color_manager_v1.whitepoint_names" summary="whitepoint"/>
</event>
<request name="destroy" type="destructor">
<description summary="destroy the color space">
Destroy the zwp_color_space_v1 object.
Destroying the zwp_color_space_v1 which is active on a surface or an
output does not change the color space of those objects.
</description>
</request>
</interface>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment