---
title: Headroom Adaptive Gain Curve
framework: colorsync
role: collectionGroup
role_heading: API Collection
path: colorsync/headroom-adaptive-gain-curve
---

# Headroom Adaptive Gain Curve

Work with SMPTE ST 2094-50 tone-mapping metadata shared between HDR stills and video.

## Overview

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 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 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 Image I/O decodes an ISO 21496-1 gain-map image to HDR with kCGImageSourceDecodeToHDR, 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 Core Graphics, Core Image, and Core Animation, including the UIImageView and NSImageView classes. Video plays through AVFoundation, 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](colorsync/authoring-headroom-adaptive-gain-curve-metadata.md)

### Detecting a curve

- [ColorSyncProfileContainsHeadroomAdaptiveGainCurve(_:)](colorsync/colorsyncprofilecontainsheadroomadaptivegaincurve(_:).md)

### Reading a curve in Swift

- [headroomAdaptiveGainCurve](colorsync/colorsyncprofile/headroomadaptivegaincurve-swift.property.md)
- [headroomAdaptiveGainCurveMetadata](colorsync/colorsyncprofile/headroomadaptivegaincurvemetadata.md)

### Describing a curve in Swift

- [ColorSyncProfile.HeadroomAdaptiveGainCurve](colorsync/colorsyncprofile/headroomadaptivegaincurve-swift.struct.md)
- [ColorSyncProfile.HeadroomAdaptiveGainCurve.ColorVolumeTransform](colorsync/colorsyncprofile/headroomadaptivegaincurve-swift.struct/colorvolumetransform-swift.struct.md)
- [ColorSyncProfile.HeadroomAdaptiveGainCurve.ColorVolumeTransform.ToneMapping](colorsync/colorsyncprofile/headroomadaptivegaincurve-swift.struct/colorvolumetransform-swift.struct/tonemapping.md)
- [ColorSyncProfile.HeadroomAdaptiveGainCurve.ColorVolumeTransform.ToneMapping.Method](colorsync/colorsyncprofile/headroomadaptivegaincurve-swift.struct/colorvolumetransform-swift.struct/tonemapping/method-swift.enum.md)
- [ColorSyncProfile.HeadroomAdaptiveGainCurve.Error](colorsync/colorsyncprofile/headroomadaptivegaincurve-swift.struct/error.md)

### Attaching a curve in Swift

- [adding(headroomAdaptiveGainCurve:)](colorsync/colorsyncprofile/adding(headroomadaptivegaincurve:).md)
- [adding(headroomAdaptiveGainCurveMetadata:options:)](colorsync/colorsyncprofile/adding(headroomadaptivegaincurvemetadata:options:).md)
- [ColorSyncProfile.HeadroomAdaptiveGainCurveOptions](colorsync/colorsyncprofile/headroomadaptivegaincurveoptions.md)

### Structuring the info dictionary

- [kColorSyncAlternateCurveCount](colorsync/kcolorsyncalternatecurvecount.md)
- [kColorSyncAlternateGainCurveInfo](colorsync/kcolorsyncalternategaincurveinfo.md)
- [kColorSyncBaselineHeadroomStops](colorsync/kcolorsyncbaselineheadroomstops.md)
- [kColorSyncCustomHDRReferenceWhite](colorsync/kcolorsynccustomhdrreferencewhite.md)
- [kColorSyncHeadroomAdaptiveGainCurveApplicationVersion](colorsync/kcolorsyncheadroomadaptivegaincurveapplicationversion.md)
- [kColorSyncHeadroomAdaptiveGainCurveColorVolumeTransform](colorsync/kcolorsyncheadroomadaptivegaincurvecolorvolumetransform.md)
- [kColorSyncHeadroomAdaptiveGainCurveInfo](colorsync/kcolorsyncheadroomadaptivegaincurveinfo.md)
- [kColorSyncHeadroomAdaptiveToneMappingInfo](colorsync/kcolorsyncheadroomadaptivetonemappinginfo.md)

### Describing gain curves

- [kColorSyncAlternateCurveHeadroomStops](colorsync/kcolorsyncalternatecurveheadroomstops.md)
- [kColorSyncCommonComponentMixing](colorsync/kcolorsynccommoncomponentmixing.md)
- [kColorSyncCommonCurveParameters](colorsync/kcolorsynccommoncurveparameters.md)
- [kColorSyncComponentMix](colorsync/kcolorsynccomponentmix.md)
- [kColorSyncControlPointSlopes](colorsync/kcolorsynccontrolpointslopes.md)
- [kColorSyncControlPointsX](colorsync/kcolorsynccontrolpointsx.md)
- [kColorSyncControlPointsY](colorsync/kcolorsynccontrolpointsy.md)
- [kColorSyncGainCurveChromaticities](colorsync/kcolorsyncgaincurvechromaticities.md)
- [kColorSyncInterpolateSlopes](colorsync/kcolorsyncinterpolateslopes.md)
- [kColorSyncMaxControlPointIndex](colorsync/kcolorsyncmaxcontrolpointindex.md)

### Weighting component-mix coefficients

- [kColorSyncCoefficientBlue](colorsync/kcolorsynccoefficientblue.md)
- [kColorSyncCoefficientComponent](colorsync/kcolorsynccoefficientcomponent.md)
- [kColorSyncCoefficientGreen](colorsync/kcolorsynccoefficientgreen.md)
- [kColorSyncCoefficientMaxRGB](colorsync/kcolorsynccoefficientmaxrgb.md)
- [kColorSyncCoefficientMinRGB](colorsync/kcolorsynccoefficientminrgb.md)
- [kColorSyncCoefficientRed](colorsync/kcolorsynccoefficientred.md)
- [kColorSyncComponentCoefficients](colorsync/kcolorsynccomponentcoefficients.md)

## See Also

### Profile and HDR metadata

- [Color profiles](colorsync/color-profiles.md)
