On 31/08/16 17:09, Daniel Vetter wrote:
> Again move it from the unmaintainable csv into DOC free-form overview
> sections.
>
> Cc: Lionel Landwerlin <lionel.g.landwerlin at intel.com>
> Signed-off-by: Daniel Vetter <daniel.vetter at intel.com>
> ---
> Documentation/gpu/drm-kms.rst | 12 +++++++++
> Documentation/gpu/kms-properties.csv | 5 ----
> drivers/gpu/drm/drm_color_mgmt.c | 48
> ++++++++++++++++++++++++++++++++++++
> include/drm/drm_color_mgmt.h | 11 ++++++---
> 4 files changed, 68 insertions(+), 8 deletions(-)
Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin at intel.com>
Just one tiny nit below.
>
> diff --git a/Documentation/gpu/drm-kms.rst b/Documentation/gpu/drm-kms.rst
> index 6be8d3359620..53b872c105d2 100644
> --- a/Documentation/gpu/drm-kms.rst
> +++ b/Documentation/gpu/drm-kms.rst
> @@ -296,6 +296,18 @@ Plane Composition Properties
> .. kernel-doc:: drivers/gpu/drm/drm_blend.c
> :export:
>
> +Color Management Properties
> +---------------------------
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
> + :doc: overview
> +
> +.. kernel-doc:: include/drm/drm_color_mgmt.h
> + :internal:
> +
> +.. kernel-doc:: drivers/gpu/drm/drm_color_mgmt.c
> + :export:
> +
> Existing KMS Properties
> -----------------------
>
> diff --git a/Documentation/gpu/kms-properties.csv
> b/Documentation/gpu/kms-properties.csv
> index 1aa2493d1ef9..1a5729c4af65 100644
> --- a/Documentation/gpu/kms-properties.csv
> +++ b/Documentation/gpu/kms-properties.csv
> @@ -24,11 +24,6 @@ Owner Module/Drivers,Group,Property Name,Type,Property
> Values,Object attached,De
> ,,âsuggested Yâ,RANGE,"Min=0, Max=0xffffffff",Connector,property to
> suggest an Y offset for a connector
> ,Optional,"""aspect ratio""",ENUM,"{ ""None"", ""4:3"", ""16:9""
> }",Connector,TDB
> ,,âdirtyâ,ENUM | IMMUTABLE,"{ ""Off"", ""On"", ""Annotate""
> }",Connector,TBD
> -,,âDEGAMMA_LUTâ,BLOB,0,CRTC,DRM property to set the degamma lookup table
> (LUT) mapping pixel data from the framebuffer before it is given to the
> transformation matrix. The data is an interpreted as an array of struct
> drm_color_lut elements. Hardware might choose not to use the full precision
> of the LUT elements nor use all the elements of the LUT (for example the
> hardware might choose to interpolate between LUT[0] and LUT[4]).
> -,,âDEGAMMA_LUT_SIZEâ,RANGE | IMMUTABLE,"Min=0, Max=UINT_MAX",CRTC,DRM
> property to gives the size of the lookup table to be set on the DEGAMMA_LUT
> property (the size depends on the underlying hardware).
> -,,âCTMâ,BLOB,0,CRTC,DRM property to set the current transformation
> matrix (CTM) apply to pixel data after the lookup through the degamma LUT and
> before the lookup through the gamma LUT. The data is an interpreted as a
> struct drm_color_ctm.
> -,,âGAMMA_LUTâ,BLOB,0,CRTC,DRM property to set the gamma lookup table
> (LUT) mapping pixel data after to the transformation matrix to data sent to
> the connector. The data is an interpreted as an array of struct drm_color_lut
> elements. Hardware might choose not to use the full precision of the LUT
> elements nor use all the elements of the LUT (for example the hardware might
> choose to interpolate between LUT[0] and LUT[4]).
> -,,âGAMMA_LUT_SIZEâ,RANGE | IMMUTABLE,"Min=0, Max=UINT_MAX",CRTC,DRM
> property to gives the size of the lookup table to be set on the GAMMA_LUT
> property (the size depends on the underlying hardware).
> i915,Generic,"""Broadcast RGB""",ENUM,"{ ""Automatic"", ""Full"", ""Limited
> 16:235"" }",Connector,"When this property is set to Limited 16:235 and CTM is
> set, the hardware will be programmed with the result of the multiplication of
> CTM by the limited range matrix to ensure the pixels normaly in the range
> 0..1.0 are remapped to the range 16/255..235/255."
> ,,âaudioâ,ENUM,"{ ""force-dvi"", ""off"", ""auto"", ""on""
> }",Connector,TBD
> ,SDVO-TV,âmodeâ,ENUM,"{ ""NTSC_M"", ""NTSC_J"", ""NTSC_443"", ""PAL_B""
> } etc.",Connector,TBD
> diff --git a/drivers/gpu/drm/drm_color_mgmt.c
> b/drivers/gpu/drm/drm_color_mgmt.c
> index aca1b7a6397c..23b792746cfd 100644
> --- a/drivers/gpu/drm/drm_color_mgmt.c
> +++ b/drivers/gpu/drm/drm_color_mgmt.c
> @@ -26,6 +26,54 @@
>
> #include "drm_crtc_internal.h"
>
> +/**
> + * DOC: overview
> + *
> + * Color management or color space adjustements is supported through a set
> of 5
> + * properties on the &drm_crtc object. They are set up by calling
> + * drm_crtc_enable_color_mgmt().
> + *
> + * "DEGAMMA_LUTâ:
> + * Blob property to set the degamma lookup table (LUT) mapping pixel data
> + * from the framebuffer before it is given to the transformation matrix.
> + * The data is an interpreted as an array of struct &drm_color_lut
> elements.
> + * Hardware might choose not to use the full precision of the LUT elements
> + * nor use all the elements of the LUT (for example the hardware might
> + * choose to interpolate between LUT[0] and LUT[4]).
> + *
> + * âDEGAMMA_LUT_SIZEâ:
> + * Unsinged range property to gives the size of the lookup table to be set
> + * on the DEGAMMA_LUT property (the size depends on the underlying
> + * hardware). If drivers support multiple LUT sizes then they should
> + * publish the largest size, and sub-sample smaller sized LUTs (e.g. for
> + * split-gamma modes) appropriately.
> + *
> + * âCTMâ:
> + * Blob property to set the current transformation matrix (CTM) apply to
> + * pixel data after the lookup through the degamma LUT and before the
> + * lookup through the gamma LUT. The data is an interpreted as a struct
> + * &drm_color_ctm.
> + *
> + * âGAMMA_LUTâ:
> + * Blob property to set the gamma lookup table (LUT) mapping pixel data
> + * after to the transformation matrix to data sent to the connector. The
s/after to the/after the/
> + * data is an interpreted as an array of struct &drm_color_lut elements.
> + * Hardware might choose not to use the full precision of the LUT elements
> + * nor use all the elements of the LUT (for example the hardware might
> + * choose to interpolate between LUT[0] and LUT[4]).
> + *
> + * âGAMMA_LUT_SIZEâ:
> + * Unsigned range property to gives the size of the lookup table to be set
> + * on the GAMMA_LUT property (the size depends on the underlying hardware).
> + * If drivers support multiple LUT sizes then they should publish the
> + * largest size, and sub-sample smaller sized LUTs (e.g. for split-gamma
> + * modes) appropriately.
> + *
> + * There is also support for a legacy gamma table, which is set up by calling
> + * drm_mode_crtc_set_gamma_size(). Drivers which support both should use
> + * drm_atomic_helper_legacy_gamma_set() to alias the legacy gamma ramp with
> the
> + * "GAMMA_LUT" property above.
> + */
>
> /**
> * drm_crtc_enable_color_mgmt - enable color management properties
> diff --git a/include/drm/drm_color_mgmt.h b/include/drm/drm_color_mgmt.h
> index 1e01c58bbe81..c767238ac9d5 100644
> --- a/include/drm/drm_color_mgmt.h
> +++ b/include/drm/drm_color_mgmt.h
> @@ -33,9 +33,14 @@ void drm_crtc_enable_color_mgmt(struct drm_crtc *crtc,
> int drm_mode_crtc_set_gamma_size(struct drm_crtc *crtc,
> int gamma_size);
>
> -/*
> - * Extract a degamma/gamma LUT value provided by user and round it to the
> - * precision supported by the hardware.
> +/**
> + * drm_color_lut_extract - clamp&round LUT entries
> + * @user_input: input value
> + * @bit_precision: number of bits the hw LUT supports
> + *
> + * Extract a degamma/gamma LUT value provided by user (in the form of
> + * &drm_color_lut entries) and round it to the precision supported by the
> + * hardware.
> */
> static inline uint32_t drm_color_lut_extract(uint32_t user_input,
> uint32_t bit_precision)
