Display Picture Quality Pipeline#

NvDisplay exposes programmable picture quality (PQ) stages through DRM atomic properties. These stages operate on the pixels that are scanned out by the display hardware and can be used to describe the input transfer function, convert color primaries, apply tonemapping, convert the post-blend output space, and program the output gamma curve.

PQ controls are split across DRM planes and CRTCs:

  • Plane properties affect the pixels before the plane is blended with the rest of the scene. These properties are used for input transfer function, input color-space conversion, and tonemapping.

  • CRTC properties affect the final blended output for a display head. These properties are used for output color-space conversion and output gamma.

Applications should set PQ properties as part of the same atomic commit that updates the related plane or CRTC state. If a blob property is not set, the driver keeps the current hardware state for that stage, or uses the default state selected by the driver during modeset.

Programming Model#

The Linux DRM driver exposes the following NvDisplay PQ controls:

Stage

DRM object

DRM property

Purpose

Input transfer function (ILUT / degamma)

Plane

NV_PLANE_DEGAMMA_TF

Selects the transfer function used to linearize input pixels.

Input CSC / gamut conversion

Plane

NV_PLANE_LMS_CTM and NV_PLANE_BLEND_CTM

Programs 3x4 matrices used for input gamut conversion.

Tonemapping LUT (TMO LUT)

Plane

NV_PLANE_TMO_LUT

Programs the tonemapping LUT for planes that expose TMO support.

Output color-space conversion (OCSC)

CRTC

NV_CRTC_OUTPUT_CTM

Programs the post-blend output color-space conversion matrix.

Output gamma correction (OLUT / regamma)

CRTC

NV_CRTC_REGAMMA_LUT

Programs the post-blend output gamma LUT.

Applications can enumerate the properties on each plane and CRTC. A property is exposed only when the corresponding hardware resource exists for that object.

Input Transfer Function (ILUT)#

The NV_PLANE_DEGAMMA_TF plane property selects the transfer function that describes the input pixels. The driver converts the property value into the NvDisplay input transfer-function configuration for the plane.

Supported property values are:

  • Default

  • Linear

  • sRGB

  • SMPTE 170M

  • PQ (Perceptual Quantizer)

Use Linear when the input surface is already in linear light. Use sRGB, SMPTE 170M, or PQ (Perceptual Quantizer) when the input surface is encoded with that transfer function. Default follows the driver default, which maps to sRGB for this pipeline.

The standard DRM plane COLOR_ENCODING and COLOR_RANGE properties are also forwarded to NvDisplay. COLOR_ENCODING selects the input colorimetry (BT.601, BT.709, or BT.2020), and COLOR_RANGE selects limited or full range.

Input Color-Space Conversion (ICSC)#

NvDisplay supports plane-level input color-space conversion through two matrix blob properties:

  • NV_PLANE_LMS_CTM

  • NV_PLANE_BLEND_CTM

Each blob uses struct drm_color_ctm_3x4 format. This is a 3x4 matrix using S31.32 sign-magnitude values. The driver passes the matrix to NVKMS and NVKMS programs the hardware-specific coefficients.

Set a property to a valid blob before the atomic commit to enable or update the corresponding matrix. Clear the blob property to disable that matrix. The properties are attached only to planes whose hardware window exposes the corresponding CSC block.

Tonemapping (TMO LUT)#

The NV_PLANE_TMO_LUT plane property programs a tonemapping LUT for planes whose hardware window supports TMO. The companion immutable property NV_PLANE_TMO_LUT_SIZE reports the required number of client-provided LUT entries.

The blob supplied to NV_PLANE_TMO_LUT contains an array of LUT entries with 16-bit color components. The expected blob size is:

NV_PLANE_TMO_LUT_SIZE * sizeof(LUT entry)

The driver formats the hardware surface internally. Applications only provide the client LUT entries; the driver adds the hardware header and interpolation entry before programming NvDisplay.

Clear NV_PLANE_TMO_LUT to disable the client-provided TMO LUT for the plane. If the property is absent on a plane, TMO is not supported on that plane.

Output Color-Space Conversion (OCSC)#

The NV_CRTC_OUTPUT_CTM CRTC property programs the output CSC matrix after plane blending. This stage affects the final output for the display head.

The blob uses struct drm_color_ctm_3x4 format, matching the plane CSC blob format described in the ICSC section. Set the property to a valid 3x4 matrix blob before the atomic commit to enable or update the matrix. Clear the blob property to disable the output CSC matrix in hardware.

Output Gamma Correction (OLUT)#

The NV_CRTC_REGAMMA_LUT CRTC property programs the regamma LUT, also known as OLUT. The companion immutable property NV_CRTC_REGAMMA_LUT_SIZE reports the required number of client-provided LUT entries.

The blob supplied to NV_CRTC_REGAMMA_LUT contains an array of LUT entries with 16-bit red, green, and blue components. The expected blob size is:

NV_CRTC_REGAMMA_LUT_SIZE * sizeof(LUT entry)

The driver formats the hardware surface internally. Applications only provide the client LUT entries; the driver adds the hardware header and interpolation entry before programming NvDisplay.

Clear NV_CRTC_REGAMMA_LUT to have the driver program the default output gamma on that head.