interpretdfd.c

/* -*- tab-width: 4; -*- */
/* vi: set sw=2 ts=4 expandtab: */

/* Copyright 2019-2020 The Khronos Group Inc.
 * SPDX-License-Identifier: Apache-2.0
 */

/**
 * @file
 * @~English
 * @brief Utility for interpreting a data format descriptor.
 * @author Andrew Garrard
 */

#include <stdint.h>
#include <stdio.h>
#include <KHR/khr_df.h>
#include "dfd.h"

static uint32_t bit_ceil(uint32_t x) {
    x -= 1;
    for (uint32_t i = 0; i < sizeof(x) * 8; ++i)
        if (1u << i > x)
            return 1u << i;
    return 0;
}

/**
 * @~English
 * @brief Interpret a Data Format Descriptor for a simple format.
 *
 * Handles "simple" cases that can be translated to things a GPU can access.
 * For simplicity, it ignores the compressed formats, which are generally a
 * single sample (and I believe are all defined to be little-endian in their
 * in-memory layout, even if some documentation confuses this).  Focuses on
 * the layout and ignores sRGB except for reporting if that is the transfer
 * function by way of a bit in the returned value.
 *
 * @param[in] DFD Pointer to a Data Format Descriptor to interpret,
 *            described as 32-bit words in native endianness.
 *            Note that this is the whole descriptor, not just
 *            the basic descriptor block.
 * @param R[in,out] Pointer to struct to receive information about the decoded
 *                  red channel, the Y channel, if YUV, or the depth channel,
 *                  if any.
 * @param G[in,out] Pointer to struct to receive information about the decoded
 *                  green channel, the U (Cb) channel, if YUV, or the stencil
 *                  channel, if any.
 * @param B[in,out] Pointer to struct to receive information about the decoded
 *                  blue channel, if any or the V (Cr) channel, if YUV.
 * @param A[in,out] Pointer to struct to receive information about the decoded
 *                  alpha channel, if any or the second Y channel, if YUV and
 *                  any.
 * @param wordBytes[in,out] Pointer to a uint32_t to receive the byte size of
 *                          the channels (unpacked) or total size (packed).
 *
 * @return An enumerant describing the decoded value,
 *         or an error code in case of failure.
 *
 * The mapping of YUV channels to the parameter names used here is based on
 * the channel ids in @c khr_df.h and is different from the convention used
 * in format names in the Vulkan specification where G == Y, R = Cr and B = Cb.
 **/
enum InterpretDFDResult interpretDFD(const uint32_t *DFD,
                                     InterpretedDFDChannel *R,
                                     InterpretedDFDChannel *G,
                                     InterpretedDFDChannel *B,
                                     InterpretedDFDChannel *A,
                                     uint32_t *wordBytes)
{
    /* DFD points to the whole descriptor, not the basic descriptor block. */
    /* Make everything else relative to the basic descriptor block. */
    const uint32_t *BDFDB = DFD+1;

    uint32_t numSamples = KHR_DFDSAMPLECOUNT(BDFDB);
    if (numSamples == 0)
        return i_UNSUPPORTED_CHANNEL_TYPES;

    int determinedEndianness = 0;
    enum InterpretDFDResult result = 0; /* Build this up incrementally. */

    bool isDepthStencil = false;

    /* Clear these so following code doesn't get confused. */
    R->offset = R->size = 0;
    G->offset = G->size = 0;
    B->offset = B->size = 0;
    A->offset = A->size = 0;

    /* First rule out the multiple planes case (trivially) */
    /* - that is, we check that only bytesPlane0 is non-zero. */
    /* This means we don't handle multi-plane YUV, even if the API could. */
    /* (We rely on KHR_DF_WORD_BYTESPLANE0..3 being the same and */
    /* KHR_DF_WORD_BYTESPLANE4..7 being the same as a short cut.) */
    if ((BDFDB[KHR_DF_WORD_BYTESPLANE0] & ~KHR_DF_MASK_BYTESPLANE0)
        || BDFDB[KHR_DF_WORD_BYTESPLANE4]) return i_UNSUPPORTED_MULTIPLE_PLANES;

    /* If this is a packed format, we work out our offsets differently. */
    /* We assume a packed format has channels that aren't byte-aligned. */
    /* If we have a format in which every channel is byte-aligned *and* packed, */
    /* we have the RGBA/ABGR ambiguity; we *probably* don't want the packed */
    /* version in this case, and if hardware has to pack it and swizzle, */
    /* that's up to the hardware to special-case. */
    for (uint32_t sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
        uint32_t offset = KHR_DFDSVAL(BDFDB, sampleCounter, BITOFFSET);
        uint32_t length = KHR_DFDSVAL(BDFDB, sampleCounter, BITLENGTH) + 1;
        if ((offset & 0x7U) || ((offset + length) & 0x7U)) {
            result |= i_PACKED_FORMAT_BIT;
            /* Once we're packed, we're packed, no need to keep checking. */
            break;
        }
    }

    // Check data types.
    bool hasSigned = false;
    bool hasFloat = false;
    bool hasNormalized = false;
    bool hasFixed = false;
    khr_df_model_e model = KHR_DFDVAL(BDFDB, MODEL);

    // Note: We're ignoring 9995, which is weird and worth special-casing
    // rather than trying to generalise to all float formats.
    for (uint32_t i = 0; i < numSamples; ++i) {
        const bool isSigned = (KHR_DFDSVAL(BDFDB, i, QUALIFIERS) & KHR_DF_SAMPLE_DATATYPE_SIGNED) != 0;
        const bool isFloat = (KHR_DFDSVAL(BDFDB, i, QUALIFIERS) & KHR_DF_SAMPLE_DATATYPE_FLOAT) != 0;

        // We define "unnormalized" as "sample_upper = 1" or "sample_upper = 1.0f".
        // We don't check whether any non-1 normalization value is correct
        // (i.e. set to the maximum bit value, and check min value) on
        // the assumption that we're looking at a format which *came* from
        // an API we can support.
        bool isFixed;
        bool isNormalized;
        if (isFloat) {
            isNormalized = *(float*) (void*) &BDFDB[KHR_DF_WORD_SAMPLESTART +
                    KHR_DF_WORD_SAMPLEWORDS * i +
                    KHR_DF_SAMPLEWORD_SAMPLEUPPER] != 1.0f;
            isFixed = false;
        } else {
            uint32_t sampleUpper = KHR_DFDSVAL(BDFDB, i, SAMPLEUPPER);
            uint32_t maxVal = 1U << KHR_DFDSVAL(BDFDB, i, BITLENGTH);
            if (!isSigned) maxVal <<= 1;
            maxVal--;
            isFixed = 1U < sampleUpper && sampleUpper < maxVal;
            isNormalized = !isFixed && sampleUpper != 1U;
        }
        hasSigned |= isSigned;
        hasFixed |= isFixed;
        hasFloat |= isFloat;
        // By our definition the normalizedness of a single bit channel (like in RGBA 5:5:5:1)
        // is ambiguous. Ignore these during normalized checks.
        if (KHR_DFDSVAL(BDFDB, i, BITLENGTH) > 0)
            hasNormalized |= isNormalized;
    }
    result |= hasSigned ? i_SIGNED_FORMAT_BIT : 0;
    result |= hasFloat ? i_FLOAT_FORMAT_BIT : 0;
    result |= hasNormalized ? i_NORMALIZED_FORMAT_BIT : 0;
    result |= hasFixed ? i_FIXED_FORMAT_BIT : 0;

    // Checks based on color model
    if (model == KHR_DF_MODEL_YUVSDA) {
        result |= i_NORMALIZED_FORMAT_BIT;
        result |= i_COMPRESSED_FORMAT_BIT;
        result |= i_YUVSDA_FORMAT_BIT;

        for (uint32_t i = 0; i < numSamples; ++i) {
            switch (KHR_DFDSVAL(BDFDB, i, CHANNELID)) {
            case KHR_DF_CHANNEL_YUVSDA_Y:
            case KHR_DF_CHANNEL_YUVSDA_U:
            case KHR_DF_CHANNEL_YUVSDA_V:
            case KHR_DF_CHANNEL_YUVSDA_A:
                break;
            case KHR_DF_CHANNEL_YUVSDA_DEPTH:
            case KHR_DF_CHANNEL_YUVSDA_STENCIL:
                isDepthStencil = true;
                break;
            default:
                return i_UNSUPPORTED_CHANNEL_TYPES;
            }
        }

        // Determine wordBytes
        uint32_t largestSampleSize = 0;
        for (uint32_t i = 0; i < numSamples; ++i) {
            uint32_t length = KHR_DFDSVAL(BDFDB, i, BITLENGTH) + 1;
            if (largestSampleSize < length)
                largestSampleSize = length;
        }
        *wordBytes = ((result & i_PACKED_FORMAT_BIT) ? 4 : 1) * bit_ceil(largestSampleSize) / 8;

    } else if (KHR_DFDVAL(BDFDB, MODEL) == KHR_DF_MODEL_RGBSDA) {
        /* Check if transfer is sRGB. */
        if (KHR_DFDVAL(BDFDB, TRANSFER) == KHR_DF_TRANSFER_SRGB) result |= i_SRGB_FORMAT_BIT;

        /* We only support samples at coordinate 0,0,0,0. */
        /* (We could confirm this from texel_block_dimensions in 1.2, but */
        /* the interpretation might change in later versions.) */
        for (uint32_t sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
            if (KHR_DFDSVAL(BDFDB, sampleCounter, SAMPLEPOSITION_ALL))
                return i_UNSUPPORTED_MULTIPLE_SAMPLE_LOCATIONS;
        }
    }

    if (model == KHR_DF_MODEL_RGBSDA || model == KHR_DF_MODEL_YUVSDA) {
        /* The values of the DEPTH and STENCIL tokens are the same for */
        /* RGBSDA and YUVSDA. */
        /* For Depth/Stencil formats mixed channels are allowed */
        for (uint32_t sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
            switch (KHR_DFDSVAL(BDFDB, sampleCounter, CHANNELID)) {
            case KHR_DF_CHANNEL_RGBSDA_DEPTH:
            case KHR_DF_CHANNEL_RGBSDA_STENCIL:
                isDepthStencil = true;
                break;
            default:
                break;
            }
        }

        // Check for mixed channels
        if (!isDepthStencil) {
            for (uint32_t i = 0; i < numSamples; ++i) {
                const bool isSigned = (KHR_DFDSVAL(BDFDB, i, QUALIFIERS) & KHR_DF_SAMPLE_DATATYPE_SIGNED) != 0;
                const bool isFloat = (KHR_DFDSVAL(BDFDB, i, QUALIFIERS) & KHR_DF_SAMPLE_DATATYPE_FLOAT) != 0;

                if (isSigned != hasSigned)
                    return i_UNSUPPORTED_MIXED_CHANNELS;
                if (isFloat != hasFloat)
                    return i_UNSUPPORTED_MIXED_CHANNELS;

                // Note: We don't check for inconsistent normalization, because
                // channels composed of multiple samples will have 0 in the
                // lower/upper range. Single bit channels are also ambiguous.
                // This heuristic should handle 64-bit integers, too.
            }
        }

        /* This all relies on the channel id values for RGB being equal to */
        /* those for YUV. */

        /* Remember: the canonical ordering of samples is to start with */
        /* the lowest bit of the channel/location which touches bit 0 of */
        /* the data, when the latter is concatenated in little-endian order, */
        /* and then progress until all the bits of that channel/location */
        /* have been processed. Multiple channels sharing the same source */
        /* bits are processed in channel ID order. (I should clarify this */
        /* for partially-shared data, but it doesn't really matter so long */
        /* as everything is consecutive, except to make things canonical.) */
        /* Note: For standard formats we could determine big/little-endianness */
        /* simply from whether the first sample starts in bit 0; technically */
        /* it's possible to have a format with unaligned channels wherein the */
        /* first channel starts at bit 0 and is one byte, yet other channels */
        /* take more bytes or aren't aligned (e.g. D24S8), but this should be */
        /* irrelevant for the formats that we support. */
        if ((result & i_PACKED_FORMAT_BIT)) {
            /* A packed format. */
            uint32_t currentChannel = ~0U; /* Don't start matched. */
            uint32_t currentBitOffset = 0;
            uint32_t currentByteOffset = 0;
            uint32_t currentBitLength = 0;
            *wordBytes = (BDFDB[KHR_DF_WORD_BYTESPLANE0] & 0xFFU);
            for (uint32_t sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
                uint32_t sampleBitOffset = KHR_DFDSVAL(BDFDB, sampleCounter, BITOFFSET);
                uint32_t sampleByteOffset = sampleBitOffset >> 3U;
                /* The sample bitLength field stores the bit length - 1. */
                uint32_t sampleBitLength = KHR_DFDSVAL(BDFDB, sampleCounter, BITLENGTH) + 1;
                uint32_t sampleChannel = KHR_DFDSVAL(BDFDB, sampleCounter, CHANNELID);
                InterpretedDFDChannel *sampleChannelPtr;
                switch (sampleChannel) {
                case KHR_DF_CHANNEL_RGBSDA_RED:
                    sampleChannelPtr = R;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_GREEN:
                    sampleChannelPtr = G;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_BLUE:
                    sampleChannelPtr = B;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_DEPTH:
                    sampleChannelPtr = R;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_STENCIL:
                    sampleChannelPtr = G;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_ALPHA:
                    sampleChannelPtr = A;
                    break;
                default:
                    return i_UNSUPPORTED_CHANNEL_TYPES;
                }
                if (sampleChannel == currentChannel) {
                    /* Continuation of the same channel. */
                    /* Since a big (>32-bit) channel isn't "packed", */
                    /* this should only happen in big-endian, or if */
                    /* we have a wacky format that we won't support. */
                    if (sampleByteOffset == currentByteOffset - 1U && /* One byte earlier */
                        ((currentBitOffset + currentBitLength) & 7U) == 0 && /* Already at the end of a byte */
                        (sampleBitOffset & 7U) == 0) { /* Start at the beginning of the byte */
                        /* All is good, continue big-endian. */
                        /* N.B. We shouldn't be here if we decided we were little-endian, */
                        /* so we don't bother to check that disagreement. */
                        result |= i_BIG_ENDIAN_FORMAT_BIT;
                        determinedEndianness = 1;
                    } else {
                        /* Oh dear. */
                        /* We could be little-endian, but not with any standard format. */
                        /* More likely we've got something weird that we can't support. */
                        return i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS;
                    }
                    /* Remember where we are. */
                    currentBitOffset = sampleBitOffset;
                    currentByteOffset = sampleByteOffset;
                    currentBitLength = sampleBitLength;
                    /* Accumulate the bit length. */
                    sampleChannelPtr->size += sampleBitLength;
                } else {
                    /* Everything is new. Hopefully. */
                    currentChannel = sampleChannel;
                    currentBitOffset = sampleBitOffset;
                    currentByteOffset = sampleByteOffset;
                    currentBitLength = sampleBitLength;
                    if (sampleChannelPtr->size) {
                        if (model == KHR_DF_MODEL_YUVSDA && sampleChannel == KHR_DF_CHANNEL_YUVSDA_Y) {
                            if (sampleChannelPtr == R) {
                                /* We've got another Y channel. Record details in A. */
                                if (A->size == 0) {
                                    sampleChannelPtr = A;
                                } else {
                                    /* Uh-oh, we've already got a second Y or an alpha channel. */
                                    return i_UNSUPPORTED_CHANNEL_TYPES;
                                }
                            }
                        } else {
                          /* Uh-oh, we've seen this channel before. */
                          return i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS;
                        }
                    }
                    /* For now, record the bit offset in little-endian terms, */
                    /* because we may not know to reverse it yet. */
                    sampleChannelPtr->offset = sampleBitOffset;
                    sampleChannelPtr->size = sampleBitLength;
                }
            }
            if ((result & i_BIG_ENDIAN_FORMAT_BIT)) {
                /* Our bit offsets to bit 0 of each channel are in little-endian terms. */
                /* We need to do a byte swap to work out where they should be. */
                /* We assume, for sanity, that byte sizes are a power of two for this. */
                uint32_t offsetMask = (*wordBytes - 1U) << 3U;
                R->offset ^= offsetMask;
                G->offset ^= offsetMask;
                B->offset ^= offsetMask;
                A->offset ^= offsetMask;
            }
        } else {
            /* Not a packed format. */
            /* Everything is byte-aligned. */
            /* Question is whether there multiple samples per channel. */
            uint32_t currentChannel = ~0U; /* Don't start matched. */
            uint32_t currentByteOffset = 0;
            uint32_t currentByteLength = 0;
            for (uint32_t sampleCounter = 0; sampleCounter < numSamples; ++sampleCounter) {
                uint32_t sampleByteOffset = KHR_DFDSVAL(BDFDB, sampleCounter, BITOFFSET) >> 3U;
                uint32_t sampleByteLength = (KHR_DFDSVAL(BDFDB, sampleCounter, BITLENGTH) + 1) >> 3U;
                uint32_t sampleChannel = KHR_DFDSVAL(BDFDB, sampleCounter, CHANNELID);
                InterpretedDFDChannel *sampleChannelPtr;
                switch (sampleChannel) {
                case KHR_DF_CHANNEL_RGBSDA_RED:
                    sampleChannelPtr = R;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_GREEN:
                    sampleChannelPtr = G;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_BLUE:
                    sampleChannelPtr = B;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_DEPTH:
                    sampleChannelPtr = R;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_STENCIL:
                    sampleChannelPtr = G;
                    break;
                case KHR_DF_CHANNEL_RGBSDA_ALPHA:
                    sampleChannelPtr = A;
                    break;
                default:
                    return i_UNSUPPORTED_CHANNEL_TYPES;
                }
                if (sampleChannel == currentChannel) {
                    /* Continuation of the same channel. */
                    /* Either big-endian, or little-endian with a very large channel. */
                    if (sampleByteOffset == currentByteOffset - 1) { /* One byte earlier */
                        if (determinedEndianness && !(result & i_BIG_ENDIAN_FORMAT_BIT)) {
                            return i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS;
                        }
                        /* All is good, continue big-endian. */
                        result |= i_BIG_ENDIAN_FORMAT_BIT;
                        determinedEndianness = 1;
                        /* Update the start */
                        sampleChannelPtr->offset = sampleByteOffset;
                    } else if (sampleByteOffset == currentByteOffset + currentByteLength) {
                        if (determinedEndianness && (result & i_BIG_ENDIAN_FORMAT_BIT)) {
                            return i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS;
                        }
                        /* All is good, continue little-endian. */
                        determinedEndianness = 1;
                    } else {
                        /* Oh dear. */
                        /* We could be little-endian, but not with any standard format. */
                        /* More likely we've got something weird that we can't support. */
                        return i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS;
                    }
                    /* Remember where we are. */
                    currentByteOffset = sampleByteOffset;
                    currentByteLength = sampleByteLength;
                    /* Accumulate the byte length. */
                    sampleChannelPtr->size += sampleByteLength;
                    /* Assume these are all the same. */
                    *wordBytes = sampleChannelPtr->size;
                } else {
                    /* Everything is new. Hopefully. */
                    currentChannel = sampleChannel;
                    currentByteOffset = sampleByteOffset;
                    currentByteLength = sampleByteLength;
                    if (sampleChannelPtr->size) {
                        if (model == KHR_DF_MODEL_YUVSDA && sampleChannel == KHR_DF_CHANNEL_YUVSDA_Y) {
                            if (sampleChannelPtr == R) {
                                /* We've got another Y channel. Record details in A. */
                                if (A->size == 0) {
                                    sampleChannelPtr = A;
                                } else {
                                    /* Uh-oh, we've already got a second Y or an alpha channel. */
                                    return i_UNSUPPORTED_CHANNEL_TYPES;
                                }
                            }
                        } else {
                          /* Uh-oh, we've seen this channel before. */
                          return i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS;
                        }
                    }
                    /* For now, record the byte offset in little-endian terms, */
                    /* because we may not know to reverse it yet. */
                    sampleChannelPtr->offset = sampleByteOffset;
                    sampleChannelPtr->size = sampleByteLength;
                    /* Assume these are all the same. */
                    *wordBytes = sampleByteLength;
                }
            }
        }
    } else {
        return i_UNSUPPORTED_CHANNEL_TYPES;
    }

    if (isDepthStencil) {
        /* For Depth/Stencil formats wordBytes is determined by the required alignment of */
        /* the larger channel. */
        uint32_t largerSize = R->size > G->size ? R->size : G->size;
        *wordBytes = bit_ceil(largerSize);
    }

    return result;
}