blob: b5cfd326dc3acc98aed106ce174787ad0e006b26 [file]
/*
* Copyright 2025 Google LLC
*
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
#ifndef SkHdrMetadata_DEFINED
#define SkHdrMetadata_DEFINED
#include "include/core/SkColorSpace.h"
#include "include/core/SkData.h"
#include "include/private/SkAPI.h"
#include <algorithm>
#include <cmath>
#include <memory>
#include <optional>
#include <vector>
class SkColorFilter;
class SkData;
class SkString;
namespace skhdr {
/**
* Content light level metadata.
* The semantics of this metadata is defined in:
* ANSI/CTA-861-H A DTV Profile for Uncompressed High Speed Digital Interfaces
* Annex P Calculation of MaxCLL and MaxFALL
* Slightly different semantics for this metadata are defined in:
* Portable Network Graphics (PNG) Specification (Third Edition)
* 11.3.2.8 cLLI Content Light Level Information
* https://www.w3.org/TR/png-3/#cLLI-chunk
* This metadata should only be used in ways that work with both semantics.
*/
struct SK_API ContentLightLevelInformation {
float fMaxCLL = 0.f;
float fMaxFALL = 0.f;
/**
* Decode from the binary encoding listed at:
* AV1 Bitstream & Decoding Process Specification Version 1.0.0 Errata 1
* https://aomediacodec.github.io/av1-spec/av1-spec.pdf
* 5.8.3 Metadata high dynamic range content light level syntax
* This encoding is equivalent to:
* ITU-T H.265 (V10) (07/2024)
* D.2.35 Content light level information SEI message syntax
* Return false if parsing fails.
*/
bool parse(const SkData* data);
/**
* Serialize to the encoding used by parse().
*/
sk_sp<SkData> serialize() const;
/**
* Helper functions for accessing members as uint16_t, which is often needed when interacting
* with libraries using the CTA semantics.
*/
static ContentLightLevelInformation MakeUint16(uint16_t maxCLL, uint16_t maxFALL) {
return { .fMaxCLL = static_cast<float>(maxCLL), .fMaxFALL = static_cast<float>(maxFALL) };
}
uint16_t getUint16MaxCLL() const {
return static_cast<uint16_t>(std::clamp(std::round(fMaxCLL), 0.f, 65535.f));
}
uint16_t getUint16MaxFALL() const {
return static_cast<uint16_t>(std::clamp(std::round(fMaxFALL), 0.f, 65535.f));
}
/**
* Decode from the binary encoding listed at:
* Portable Network Graphics (PNG) Specification (Third Edition)
* 11.3.2.8 cLLI Content Light Level Information
* https://www.w3.org/TR/png-3/#cLLI-chunk
* This encoding is not equivalent to the encoding used by parse().
* Return false if parsing fails.
*/
bool parsePngChunk(const SkData* data);
/**
* Serialize to the encoding used by parsePngChunk().
*/
sk_sp<SkData> serializePngChunk() const;
/**
* Return a human-readable description.
*/
SkString toString() const;
bool operator==(const ContentLightLevelInformation& other) const;
bool operator!=(const ContentLightLevelInformation& other) const {
return !(*this == other);
}
};
/**
* Mastering display color volume metadata.
* The semantics of this metadata is defined in:
* SMPTE ST 2086:2018 Mastering Display Color Volume Metadata Supporting
* High Luminance and Wide Color Gamut Images
*/
struct SK_API MasteringDisplayColorVolume {
SkColorSpacePrimaries fDisplayPrimaries = {0.f, 0.f, 0.f, 0.f, 0.f, 0.f, 0.f, 0.f};
float fMaximumDisplayMasteringLuminance = 0.f;
float fMinimumDisplayMasteringLuminance = 0.f;
/**
* The encoding as defined in:
* AV1 Bitstream & Decoding Process Specification Version 1.0.0 Errata 1
* https://aomediacodec.github.io/av1-spec/av1-spec.pdf
* 5.8.4 Metadata high dynamic range mastering display color volume syntax
* This encoding is equivalent to:
* ITU-T H.265 (V10) (07/2024)
* D.2.35 Content light level information SEI message syntax
* This encoding is also equivalent to:
* Portable Network Graphics (PNG) Specification (Third Edition)
* 11.3.2.7 mDCV Mastering Display Color Volume
* https://www.w3.org/TR/png-3/#mDCV-chunk
* Return false if parsing fails.
*/
bool parse(const SkData* data);
/**
* Serialize to the encoding used by parse().
*/
sk_sp<SkData> serialize() const;
/**
* Return a human-readable description.
*/
SkString toString() const;
bool operator==(const MasteringDisplayColorVolume& other) const;
bool operator!=(const MasteringDisplayColorVolume& other) const {
return !(*this == other);
}
};
/**
* Adaptive Global Tone Map
* This structure contains the metadata items from the ColorVolumeTransform metadata group
* in Clause 7.1: Metadata set of SMPTE ST 2094-50: Dynamic metadata for color volume transform
* Application #5
* https://github.com/SMPTE/st2094-50
* WARNING: This specification is still a DRAFT and is subject to change before publication.
*/
struct SK_API AdaptiveGlobalToneMap {
// A GainCurve metadata group.
struct SK_API GainCurve {
// Structure holding one entry of the GainCurveControlPointX, GainCurveControlPointY, and
// GainCurveControlPointM metadata items.
struct ControlPoint {
float fX = 0.f;
float fY = 0.f;
float fM = 0.f;
bool operator==(const ControlPoint& other) const {
return fX == other.fX && fY == other.fY && fM == other.fM;
}
};
// The size of this vector is the value of the GainCurveNumControlPoints metadata item.
static constexpr size_t kMinNumControlPoints = 1u;
static constexpr size_t kMaxNumControlPoints = 32u;
std::vector<ControlPoint> fControlPoints = {};
bool operator==(const GainCurve& other) const {
return fControlPoints == other.fControlPoints;
}
};
// A ComponentMix metadata group.
struct SK_API ComponentMixingFunction {
// The ComponentMixRed/Green/Blue/Max/Min/Component metadata items.
float fRed = 0.f;
float fGreen = 0.f;
float fBlue = 0.f;
float fMax = 0.f;
float fMin = 0.f;
float fComponent = 0.f;
bool operator==(const ComponentMixingFunction& other) const {
return fRed == other.fRed && fGreen == other.fGreen && fBlue == other.fBlue &&
fMax == other.fMax && fMin == other.fMin && fComponent == other.fComponent;
}
};
// A ColorGainFunction metadata group.
struct SK_API ColorGainFunction {
// The ComponentMix metadata group.
ComponentMixingFunction fComponentMixing = {};
// The GainCurve metadata group.
GainCurve fGainCurve = {};
bool operator==(const ColorGainFunction& other) const {
return fComponentMixing == other.fComponentMixing && fGainCurve == other.fGainCurve;
}
};
// Structure holding the metadata items and groups for an alternate image.
struct SK_API AlternateImage {
// The AlternateHdrHeadroom metadata item.
float fHdrHeadroom = 0.f;
// The ColorGainFunction metadata group.
ColorGainFunction fColorGainFunction = {};
bool operator==(const AlternateImage& other) const {
return fHdrHeadroom == other.fHdrHeadroom && fColorGainFunction == other.fColorGainFunction;
}
};
// HeadroomAdaptiveToneMap metadata group.
struct SK_API HeadroomAdaptiveToneMap {
// The BaselineHdrHeadroom metadata item.
float fBaselineHdrHeadroom = 0.f;
// The GainApplicationSpaceColorPrimaries metadata item.
SkColorSpacePrimaries fGainApplicationSpacePrimaries =
{0.f, 0.f, 0.f, 0.f, 0.f, 0.f, 0.f, 0.f};
// The size of this vector is the NumAlternateImages metadata item.
static constexpr size_t kMaxNumAlternateImages = 4u;
std::vector<AlternateImage> fAlternateImages = {};
bool operator==(const HeadroomAdaptiveToneMap& other) const {
return fBaselineHdrHeadroom == other.fBaselineHdrHeadroom &&
fGainApplicationSpacePrimaries == other.fGainApplicationSpacePrimaries &&
fAlternateImages == other.fAlternateImages;
}
};
// The default value for the HdrReferenceWhite metadata item.
static constexpr float kDefaultHdrReferenceWhite = 203.f;
// The HdrReferenceWhite metadata item.
float fHdrReferenceWhite = kDefaultHdrReferenceWhite;
// The HeadroomAdaptiveToneMap metadata group.
std::optional<HeadroomAdaptiveToneMap> fHeadroomAdaptiveToneMap = std::nullopt;
/**
* Decode from the binary encoding in Annex C.
*/
bool parse(const SkData* data);
/**
* Serialize to the encoding used by parse().
*/
sk_sp<SkData> serialize() const;
/**
* Return a human-readable description.
*/
SkString toString() const;
/**
* Return true if this metadata satisfies all normative constraints.
*/
bool isValid() const;
bool operator==(const AdaptiveGlobalToneMap& other) const {
return fHdrReferenceWhite == other.fHdrReferenceWhite &&
fHeadroomAdaptiveToneMap == other.fHeadroomAdaptiveToneMap;
}
};
/**
* Structure containing all HDR metadata that can be attached to an image or video frame.
*/
class SK_API Metadata {
public:
/**
* Return a container with no metadata.
*/
static Metadata MakeEmpty();
/**
* If there does not exists Content Light Level Information metadata, then return false.
* Otherwise return true and if `clli` is non-nullptr then write the metadata to `clli`.
*/
bool getContentLightLevelInformation(ContentLightLevelInformation* clli) const;
/**
* Set the Content Light Level Information metadata.
*/
void setContentLightLevelInformation(const ContentLightLevelInformation& clli);
/**
* If there does not exists Mastering Display Color Volume metadata, then return false.
* Otherwise return true and if `mdcv` is non-nullptr then write the metadata to `mdcv`.
*/
bool getMasteringDisplayColorVolume(MasteringDisplayColorVolume* mdcv) const;
/**
* Set the Mastering Display Color Volume metadata.
*/
void setMasteringDisplayColorVolume(const MasteringDisplayColorVolume& mdcv);
/**
* If there does not exists Adaptive Global Tone Map metadata, then return false.
* Otherwise return true and if `agtm` is non-nullptr then write the metadata to `agtm`.
*/
bool getAdaptiveGlobalToneMap(AdaptiveGlobalToneMap* agtm) const;
/**
* Set the Adaptive Global Tone Map metadata.
*/
void setAdaptiveGlobalToneMap(const AdaptiveGlobalToneMap& agtm);
/**
* Return the serialized Adaptive Global Tone Mapping metadata, or nullptr if none has been set.
*/
sk_sp<const SkData> getSerializedAgtm() const;
/**
* Set the serialized Adaptive Global Tone Mapping metadata.
*/
void setSerializedAgtm(sk_sp<const SkData>);
/**
* Return a human-readable description.
*/
SkString toString() const;
/**
* Return the SkColorFilter to tone map to the specified targeted HDR headroom.
*
* The `inputColorSpace` parameter is the color space of the input image that will be
* used with the image. If it is PQ or HLG, then the color filter will effectively
* reinterpret the image as having the HDR reference white parameter indicated in the
* metadata.
*
* If `inputColorSpace` is PQ or HLG, then a default tone mapping will be provided,
* inferring the baseline HDR headroom from the CLLI or MDCV metadata, if present.
*/
sk_sp<SkColorFilter> makeToneMapColorFilter(
float targetedHdrHeadroom, const SkColorSpace* inputColorSpace = nullptr) const;
bool operator==(const Metadata& other) const;
bool operator!=(const Metadata& other) const {
return !(*this == other);
}
private:
std::optional<ContentLightLevelInformation> fContentLightLevelInformation;
std::optional<MasteringDisplayColorVolume> fMasteringDisplayColorVolume;
std::optional<AdaptiveGlobalToneMap> fAdaptiveGlobalToneMap;
};
} // namespace skhdr
#endif