drm/doc: Document color space handling

Again move it from the unmaintainable csv into DOC free-form overview
sections.

v2: Types Lionel&Sean spotted.

Cc: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
Reviewed-by: Sean Paul <seanpaul@chromium.org>
Reviewed-by: Lionel Landwerlin <lionel.g.landwerlin@intel.com>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Sean Paul <seanpaul@chromium.org>
Link: http://patchwork.freedesktop.org/patch/msgid/1474448370-32227-6-git-send-email-daniel.vetter@ffwll.ch

1 files changed, 48 insertions, 0 deletions

diff --git a/drivers/gpu/drm/drm_color_mgmt.c b/drivers/gpu/drm/drm_color_mgmt.c
index aca1b7a6397c..d28ffdd2b929 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 adjustments 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 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 give 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 interpreted as a struct
+ *	&drm_color_ctm.
+ *
+ * “GAMMA_LUT”:
+ *	Blob property to set the gamma lookup table (LUT) mapping pixel data
+ *	after the transformation matrix to data sent to the connector. The
+ *	data is 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 give 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