Enum Request

#[non_exhaustive]
pub enum Request<'a> {
    Create {},
    SetTfNamed {
        tf: WEnum<TransferFunction>,
    },
    SetTfPower {
        eexp: u32,
    },
    SetPrimariesNamed {
        primaries: WEnum<Primaries>,
    },
    SetPrimaries {
        r_x: i32,
        r_y: i32,
        g_x: i32,
        g_y: i32,
        b_x: i32,
        b_y: i32,
        w_x: i32,
        w_y: i32,
    },
    SetLuminances {
        min_lum: u32,
        max_lum: u32,
        reference_lum: u32,
    },
    SetMasteringDisplayPrimaries {
        r_x: i32,
        r_y: i32,
        g_x: i32,
        g_y: i32,
        b_x: i32,
        b_y: i32,
        w_x: i32,
        w_y: i32,
    },
    SetMasteringLuminance {
        min_lum: u32,
        max_lum: u32,
    },
    SetMaxCll {
        max_cll: u32,
    },
    SetMaxFall {
        max_fall: u32,
    },
}

Available on crate feature wayland and Linux only.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Create

Create the image description object using params

Create an image description object based on the parameters previously set on this object.

The completeness of the parameter set is verified. If the set is not complete, the protocol error incomplete_set is raised. For the definition of a complete set, see the description of this interface.

When both max_cll and max_fall are set, max_fall must be less or equal to max_cll otherwise the invalid_luminance protocol error is raised.

In version 1, these following conditions also result in the invalid_luminance protocol error. Version 2 and later do not have this requirement.

• When max_cll is set, it must be greater than min L and less or equal to max L of the mastering luminance range.
• When max_fall is set, it must be greater than min L and less or equal to max L of the mastering luminance range.

If the particular combination of the parameter set is not supported by the compositor, the resulting image description object shall immediately deliver the wp_image_description_v1.failed event with the ‘unsupported’ cause. If a valid image description was created from the parameter set, the wp_image_description_v1.ready event will eventually be sent instead.

This request destroys the wp_image_description_creator_params_v1 object.

The resulting image description object does not allow get_information request.

This is a destructor, once sent this object cannot be used any longer.

SetTfNamed

named transfer characteristic

Sets the transfer characteristic using explicitly enumerated named functions.

When the resulting image description is attached to an image, the content should be decoded according to the industry standard practices for the transfer characteristic.

Only names advertised with wp_color_manager_v1 event supported_tf_named are allowed. Other values shall raise the protocol error invalid_tf.

If transfer characteristic has already been set on this object, the protocol error already_set is raised.

Fields

tf: WEnum<TransferFunction>

named transfer function

SetTfPower

transfer characteristic as a power curve

Sets the color component transfer characteristic to a power curve with the given exponent. Negative values are handled by mirroring the positive half of the curve through the origin. The valid domain and range of the curve are all finite real numbers. This curve represents the conversion from electrical to optical color channel values.

The curve exponent shall be multiplied by 10000 to get the argument eexp value to carry the precision of 4 decimals.

The curve exponent must be at least 1.0 and at most 10.0. Otherwise the protocol error invalid_tf is raised.

If transfer characteristic has already been set on this object, the protocol error already_set is raised.

This request can be used when the compositor advertises wp_color_manager_v1.feature.set_tf_power. Otherwise this request raises the protocol error unsupported_feature.

Fields

eexp: u32

the exponent * 10000

SetPrimariesNamed

named primaries

Sets the color primaries and white point using explicitly named sets. This describes the primary color volume which is the basis for color value encoding.

Only names advertised with wp_color_manager_v1 event supported_primaries_named are allowed. Other values shall raise the protocol error invalid_primaries_named.

If primaries have already been set on this object, the protocol error already_set is raised.

Fields

primaries: WEnum<Primaries>

named primaries

SetPrimaries

primaries as chromaticity coordinates

Sets the color primaries and white point using CIE 1931 xy chromaticity coordinates. This describes the primary color volume which is the basis for color value encoding.

Each coordinate value is multiplied by 1 million to get the argument value to carry precision of 6 decimals.

If primaries have already been set on this object, the protocol error already_set is raised.

This request can be used if the compositor advertises wp_color_manager_v1.feature.set_primaries. Otherwise this request raises the protocol error unsupported_feature.

Fields

r_x: i32

Red x * 1M

r_y: i32

Red y * 1M

g_x: i32

Green x * 1M

g_y: i32

Green y * 1M

b_x: i32

Blue x * 1M

b_y: i32

Blue y * 1M

w_x: i32

White x * 1M

w_y: i32

White y * 1M

SetLuminances

primary color volume luminance range and reference white

Sets the primary color volume luminance range and the reference white luminance level. These values include the minimum display emission, but not external flare. The minimum display emission is assumed to have the chromaticity of the primary color volume white point.

The default luminances from https://www.color.org/chardata/rgb/srgb.xalter are

• primary color volume minimum: 0.2 cd/m²
• primary color volume maximum: 80 cd/m²
• reference white: 80 cd/m²

Setting a named transfer characteristic can imply other default luminances.

The default luminances get overwritten when this request is used. With transfer_function.st2084_pq the given ‘max_lum’ value is ignored, and ‘max_lum’ is taken as ‘min_lum’ + 10000 cd/m².

‘min_lum’ and ‘max_lum’ specify the minimum and maximum luminances of the primary color volume as reproduced by the targeted display.

‘reference_lum’ specifies the luminance of the reference white as reproduced by the targeted display, and reflects the targeted viewing environment.

Compositors should make sure that all content is anchored, meaning that an input signal level of ‘reference_lum’ on one image description and another input signal level of ‘reference_lum’ on another image description should produce the same output level, even though the ‘reference_lum’ on both image representations can be different.

‘reference_lum’ may be higher than ‘max_lum’. In that case reaching the reference white output level in image content requires the ‘extended_target_volume’ feature support.

If ‘max_lum’ or ‘reference_lum’ are less than or equal to ‘min_lum’, the protocol error invalid_luminance is raised.

The minimum luminance is multiplied by 10000 to get the argument ‘min_lum’ value and carries precision of 4 decimals. The maximum luminance and reference white luminance values are unscaled.

If the primary color volume luminance range and the reference white luminance level have already been set on this object, the protocol error already_set is raised.

This request can be used if the compositor advertises wp_color_manager_v1.feature.set_luminances. Otherwise this request raises the protocol error unsupported_feature.

Fields

min_lum: u32

minimum luminance (cd/m²) * 10000

max_lum: u32

maximum luminance (cd/m²)

reference_lum: u32

reference white luminance (cd/m²)

SetMasteringDisplayPrimaries

mastering display primaries as chromaticity coordinates

Provides the color primaries and white point of the mastering display using CIE 1931 xy chromaticity coordinates. This is compatible with the SMPTE ST 2086 definition of HDR static metadata.

The mastering display primaries and mastering display luminances define the target color volume.

If mastering display primaries are not explicitly set, the target color volume is assumed to have the same primaries as the primary color volume.

The target color volume is defined by all tristimulus values between 0.0 and 1.0 (inclusive) of the color space defined by the given mastering display primaries and white point. The colorimetry is identical between the container color space and the mastering display color space, including that no chromatic adaptation is applied even if the white points differ.

The target color volume can exceed the primary color volume to allow for a greater color volume with an existing color space definition (for example scRGB). It can be smaller than the primary color volume to minimize gamut and tone mapping distances for big color spaces (HDR metadata).

To make use of the entire target color volume a suitable pixel format has to be chosen (e.g. floating point to exceed the primary color volume, or abusing limited quantization range as with xvYCC).

Each coordinate value is multiplied by 1 million to get the argument value to carry precision of 6 decimals.

If mastering display primaries have already been set on this object, the protocol error already_set is raised.

This request can be used if the compositor advertises wp_color_manager_v1.feature.set_mastering_display_primaries. Otherwise this request raises the protocol error unsupported_feature. The advertisement implies support only for target color volumes fully contained within the primary color volume.

If a compositor additionally supports target color volume exceeding the primary color volume, it must advertise wp_color_manager_v1.feature.extended_target_volume. If a client uses target color volume exceeding the primary color volume and the compositor does not support it, the result is implementation defined. Compositors are recommended to detect this case and fail the image description gracefully, but it may as well result in color artifacts.

Fields

r_x: i32

Red x * 1M

r_y: i32

Red y * 1M

g_x: i32

Green x * 1M

g_y: i32

Green y * 1M

b_x: i32

Blue x * 1M

b_y: i32

Blue y * 1M

w_x: i32

White x * 1M

w_y: i32

White y * 1M

SetMasteringLuminance

display mastering luminance range

Sets the luminance range that was used during the content mastering process as the minimum and maximum absolute luminance L. These values include the minimum display emission and ambient flare luminances, assumed to be optically additive and have the chromaticity of the primary color volume white point. This should be compatible with the SMPTE ST 2086 definition of HDR static metadata.

The mastering display primaries and mastering display luminances define the target color volume.

If mastering luminances are not explicitly set, the target color volume is assumed to have the same min and max luminances as the primary color volume.

If max L is less than or equal to min L, the protocol error invalid_luminance is raised.

Min L value is multiplied by 10000 to get the argument min_lum value and carry precision of 4 decimals. Max L value is unscaled for max_lum.

This request can be used if the compositor advertises wp_color_manager_v1.feature.set_mastering_display_primaries. Otherwise this request raises the protocol error unsupported_feature. The advertisement implies support only for target color volumes fully contained within the primary color volume.

If a compositor additionally supports target color volume exceeding the primary color volume, it must advertise wp_color_manager_v1.feature.extended_target_volume. If a client uses target color volume exceeding the primary color volume and the compositor does not support it, the result is implementation defined. Compositors are recommended to detect this case and fail the image description gracefully, but it may as well result in color artifacts.

Fields

min_lum: u32

min L (cd/m²) * 10000

max_lum: u32

max L (cd/m²)

SetMaxCll

maximum content light level

Sets the maximum content light level (max_cll) as defined by CTA-861-H.

max_cll is undefined by default.

Fields

max_cll: u32

Maximum content light level (cd/m²)

SetMaxFall

maximum frame-average light level

Sets the maximum frame-average light level (max_fall) as defined by CTA-861-H.

max_fall is undefined by default.

Fields

max_fall: u32

Maximum frame-average light level (cd/m²)

Implementations

impl<'a> Request<'a>

pub fn opcode(&self) -> u16

Get the opcode number of this message

Trait Implementations

impl<'a> Debug for Request<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.