# Headroom Adaptive Gain Curve Work with SMPTE ST 2094-50 tone-mapping metadata shared between HDR stills and video. ## Overview A Headroom Adaptive Gain Curve (HAGC) is tone-mapping metadata that describes how an HDR image or video adapts its highlights, midtones, and shadows for a display. The metadata takes effect when a display’s *headroom*, the brightness it can show above reference white, is less than the content needs. An HAGC combines an HDR reference white anchor, the content value mapped to the display’s reference white, and an optional set of gain curves, following the SMPTE ST 2094-50 standard and the matching ICC HAGC profile tag. Because still images and video share one binary representation, you can move the metadata you add to a still into a video stream, and move metadata from a video stream into a still. ColorSync provides HAGC through two APIs that describe the same data: - In Swift, use [`ColorSyncProfile.HeadroomAdaptiveGainCurve`](/documentation/ColorSync/ColorSyncProfile/HeadroomAdaptiveGainCurve-swift.struct) to check the curve’s structure at compile time and report invalid values by throwing an error. - In a C dictionary or binary API, use [`ColorSyncProfile`](/documentation/ColorSync/ColorSyncProfile) to read an info dictionary or the raw SMPTE ST 2094-50 binary payload, and create a copy of an ICC profile with the HAGC tag attached. > Note: An ICC profile can carry an HAGC tag only when its transfer function is PQ, HLG, or linear. When decodes an ISO 21496-1 gain-map image to HDR with , it derives HAGC metadata automatically by analyzing the ISO gain map. When the SDR target isn’t known or can’t be computed, the HAGC metadata can indicate a default headroom-adaptive tone mapping, the Reference White Tone Mapping Operator (RWTMO), which is the recommended tone mapping for ISO 22028-5 images. The system applies HAGC metadata embedded in HDR images and video automatically. Stills render through , , and , including the and classes. Video plays through , which carries the HAGC metadata as a SMPTE ST 2094-50 binary payload in a timed-metadata `it35` (ITU-T T.35) `mebx` track, identified by `it35/B500900001:SMPTE-ST2094-50`. ## Topics ### Authoring a gain curve [Authoring Headroom Adaptive Gain Curve metadata](/documentation/ColorSync/authoring-headroom-adaptive-gain-curve-metadata) Create tone-mapping metadata that adapts HDR content to a display’s headroom. ### Detecting a curve [`ColorSyncProfileContainsHeadroomAdaptiveGainCurve`](/documentation/ColorSync/ColorSyncProfileContainsHeadroomAdaptiveGainCurve(_:)) Returns whether a profile contains a Headroom Adaptive Gain Curve tag. ### Reading a curve in Swift [`headroomAdaptiveGainCurve`](/documentation/ColorSync/ColorSyncProfile/headroomAdaptiveGainCurve-swift.property) The Headroom Adaptive Gain Curve embedded in this profile, or `nil` if it carries no HAGC tag. [`headroomAdaptiveGainCurveMetadata`](/documentation/ColorSync/ColorSyncProfile/headroomAdaptiveGainCurveMetadata) The raw Headroom Adaptive Gain Curve data embedded in this profile, or `nil` if it carries no HAGC tag. ### Describing a curve in Swift [`HeadroomAdaptiveGainCurve`](/documentation/ColorSync/ColorSyncProfile/HeadroomAdaptiveGainCurve-swift.struct) Headroom Adaptive Gain Curve metadata that describes how to tone map a profile’s HDR content to the dynamic range available on the display. [`ColorVolumeTransform`](/documentation/ColorSync/ColorSyncProfile/HeadroomAdaptiveGainCurve-swift.struct/ColorVolumeTransform-swift.struct) A color volume transform that maps HDR content into a display’s dynamic range. [`ToneMapping`](/documentation/ColorSync/ColorSyncProfile/HeadroomAdaptiveGainCurve-swift.struct/ColorVolumeTransform-swift.struct/ToneMapping) Headroom-adaptive tone mapping that adjusts HDR content to the display’s available headroom. [`Method`](/documentation/ColorSync/ColorSyncProfile/HeadroomAdaptiveGainCurve-swift.struct/ColorVolumeTransform-swift.struct/ToneMapping/Method-swift.enum) The tone-mapping method: reference-white-based, or a headroom-adaptive gain curve. [`Error`](/documentation/ColorSync/ColorSyncProfile/HeadroomAdaptiveGainCurve-swift.struct/Error) An error thrown while constructing Headroom Adaptive Gain Curve metadata. ### Attaching a curve in Swift [`adding(headroomAdaptiveGainCurve:)`](/documentation/ColorSync/ColorSyncProfile/adding(headroomAdaptiveGainCurve:)) Returns a copy of this profile with raw Headroom Adaptive Gain Curve data embedded as an HAGC tag. [`adding(headroomAdaptiveGainCurveMetadata:options:)`](/documentation/ColorSync/ColorSyncProfile/adding(headroomAdaptiveGainCurveMetadata:options:)) Returns a copy of this profile with raw Headroom Adaptive Gain Curve data embedded as an HAGC tag. [`HeadroomAdaptiveGainCurveOptions`](/documentation/ColorSync/ColorSyncProfile/HeadroomAdaptiveGainCurveOptions) Options that configure how a Headroom Adaptive Gain Curve is read from or embedded in a profile. ### Reading a curve (C API) [`ColorSyncProfileCopyHeadroomAdaptiveGainCurveInfoDictionary`](/documentation/ColorSync/ColorSyncProfileCopyHeadroomAdaptiveGainCurveInfoDictionary) Returns a dictionary describing the Headroom Adaptive Gain Curve decoded from a profile. [`ColorSyncProfileCopyHeadroomAdaptiveGainCurveMetadata`](/documentation/ColorSync/ColorSyncProfileCopyHeadroomAdaptiveGainCurveMetadata) Returns a copy of the raw Headroom Adaptive Gain Curve data embedded in a profile. ### Attaching a curve (C API) [`ColorSyncProfileCreateCopyWithHeadroomAdaptiveGainCurveInfoDictionary`](/documentation/ColorSync/ColorSyncProfileCreateCopyWithHeadroomAdaptiveGainCurveInfoDictionary) Returns a copy of a profile with an HAGC tag synthesized from an info dictionary. [`ColorSyncProfileCreateCopyWithHeadroomAdaptiveGainCurveMetadata`](/documentation/ColorSync/ColorSyncProfileCreateCopyWithHeadroomAdaptiveGainCurveMetadata) Returns a copy of a profile with the supplied Headroom Adaptive Gain Curve data embedded as an HAGC tag. ### Structuring the info dictionary [`kColorSyncAlternateCurveCount`](/documentation/ColorSync/kColorSyncAlternateCurveCount) Number of alternate (tone-mapped) curves encoded in the metadata (uint8_t in the range [0, 4]). Each alternate targets a different display headroom. [`kColorSyncAlternateGainCurveInfo`](/documentation/ColorSync/kColorSyncAlternateGainCurveInfo) CFArrayRef of per-alternate dictionaries. [`kColorSyncBaselineHeadroomStops`](/documentation/ColorSync/kColorSyncBaselineHeadroomStops) Headroom of the source (baseline) curve in stops (log2) above reference white (float in the range [0.0, 6.0]). [`kColorSyncCustomHDRReferenceWhite`](/documentation/ColorSync/kColorSyncCustomHDRReferenceWhite) Custom reference white luminance in nits (float), overriding the standard 203-nit reference white. [`kColorSyncHeadroomAdaptiveGainCurveApplicationVersion`](/documentation/ColorSync/kColorSyncHeadroomAdaptiveGainCurveApplicationVersion) Application version (uint8_t). 3-bit field from ST 2094-50 Table C.1. Must be `0`; the framework rejects any other value. [`kColorSyncHeadroomAdaptiveGainCurveColorVolumeTransform`](/documentation/ColorSync/kColorSyncHeadroomAdaptiveGainCurveColorVolumeTransform) Top-level container (CFDictionaryRef) for the color volume transform. [`kColorSyncHeadroomAdaptiveGainCurveInfo`](/documentation/ColorSync/kColorSyncHeadroomAdaptiveGainCurveInfo) Container (CFDictionaryRef) for the adaptive gain curve data. [`kColorSyncHeadroomAdaptiveToneMappingInfo`](/documentation/ColorSync/kColorSyncHeadroomAdaptiveToneMappingInfo) Container (CFDictionaryRef) for Headroom-Adaptive tone mapping parameters. ### Describing gain curves [`kColorSyncAlternateCurveHeadroomStops`](/documentation/ColorSync/kColorSyncAlternateCurveHeadroomStops) Target headroom of this alternate curve in stops (log2) above reference white (float in the range [0.0, 6.0]). The renderer selects the closest alternate to the actual display headroom. [`kColorSyncCommonComponentMixing`](/documentation/ColorSync/kColorSyncCommonComponentMixing) CFBooleanRef indicating whether alternate curves share one component-mixing configuration. [`kColorSyncCommonCurveParameters`](/documentation/ColorSync/kColorSyncCommonCurveParameters) CFBooleanRef indicating whether alternate curves share common gain-curve parameters. [`kColorSyncComponentMix`](/documentation/ColorSync/kColorSyncComponentMix) Component mixing type (uint8_t) matching `component_mixing_value` in ST 2094-50. [`kColorSyncControlPointSlopes`](/documentation/ColorSync/kColorSyncControlPointSlopes) CFArrayRef of floats — explicit tangent slopes at each control point, expressed as tan(slope_angle). Only present when [`kColorSyncInterpolateSlopes`](/documentation/ColorSync/kColorSyncInterpolateSlopes) is false. [`kColorSyncControlPointsX`](/documentation/ColorSync/kColorSyncControlPointsX) CFArrayRef of floats — the X-axis coordinates of the gain-curve control points. [`kColorSyncControlPointsY`](/documentation/ColorSync/kColorSyncControlPointsY) CFArrayRef of floats — the Y-axis gain offsets at the control points. [`kColorSyncGainCurveChromaticities`](/documentation/ColorSync/kColorSyncGainCurveChromaticities) Chromaticity primaries used to compute the driving signal for the gain curve. [`kColorSyncInterpolateSlopes`](/documentation/ColorSync/kColorSyncInterpolateSlopes) CFBooleanRef controlling how the framework determines control-point slopes. [`kColorSyncMaxControlPointIndex`](/documentation/ColorSync/kColorSyncMaxControlPointIndex) Index of the last control point (uint8_t, 0–31), i.e. the number of control points minus 1. Shared across all alternates from index 0 when [`kColorSyncCommonCurveParameters`](/documentation/ColorSync/kColorSyncCommonCurveParameters) is true. ### Weighting component-mix coefficients [`kColorSyncCoefficientBlue`](/documentation/ColorSync/kColorSyncCoefficientBlue) Weight for the blue channel in the free-style component mixing sum. [`kColorSyncCoefficientComponent`](/documentation/ColorSync/kColorSyncCoefficientComponent) Weight for the ‘component’ term in the free-style component mixing sum. [`kColorSyncCoefficientGreen`](/documentation/ColorSync/kColorSyncCoefficientGreen) Weight for the green channel in the free-style component mixing sum. [`kColorSyncCoefficientMaxRGB`](/documentation/ColorSync/kColorSyncCoefficientMaxRGB) Weight for the MAX(R,G,B) term in the free-style component mixing sum. [`kColorSyncCoefficientMinRGB`](/documentation/ColorSync/kColorSyncCoefficientMinRGB) Weight for the MIN(R,G,B) term in the free-style component mixing sum. [`kColorSyncCoefficientRed`](/documentation/ColorSync/kColorSyncCoefficientRed) Weight for the red channel in the free-style component mixing sum. [`kColorSyncComponentCoefficients`](/documentation/ColorSync/kColorSyncComponentCoefficients) Sub-dictionary of custom linear-combination coefficients for free-style component mixing. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)