1/* -*- tab-width: 4; -*- */
2/* vi: set sw=2 ts=4 expandtab: */
3
4/* Copyright 2019-2020 The Khronos Group Inc.
5 * SPDX-License-Identifier: Apache-2.0
6 */
7
8/**
9 * @file
10 * @~English
11 * @brief Header file defining the data format descriptor utilities API.
12 */
13
14/*
15 * Author: Andrew Garrard
16 */
17
18#ifndef _DFD_H_
19#define _DFD_H_
20
21#include <KHR/khr_df.h>
22
23#ifdef __cplusplus
24extern "C" {
25#endif
26
27/** Qualifier suffix to the format, in Vulkan terms. */
28enum VkSuffix {
29 s_UNORM, /*!< Unsigned normalized format. */
30 s_SNORM, /*!< Signed normalized format. */
31 s_USCALED, /*!< Unsigned scaled format. */
32 s_SSCALED, /*!< Signed scaled format. */
33 s_UINT, /*!< Unsigned integer format. */
34 s_SINT, /*!< Signed integer format. */
35 s_SFLOAT, /*!< Signed float format. */
36 s_UFLOAT, /*!< Unsigned float format. */
37 s_SRGB /*!< sRGB normalized format. */
38};
39
40/** Compression scheme, in Vulkan terms. */
41enum VkCompScheme {
42 c_BC1_RGB, /*!< BC1, aka DXT1, no alpha. */
43 c_BC1_RGBA, /*!< BC1, aka DXT1, punch-through alpha. */
44 c_BC2, /*!< BC2, aka DXT2 and DXT3. */
45 c_BC3, /*!< BC3, aka DXT4 and DXT5. */
46 c_BC4, /*!< BC4. */
47 c_BC5, /*!< BC5. */
48 c_BC6H, /*!< BC6h HDR format. */
49 c_BC7, /*!< BC7. */
50 c_ETC2_R8G8B8, /*!< ETC2 no alpha. */
51 c_ETC2_R8G8B8A1, /*!< ETC2 punch-through alpha. */
52 c_ETC2_R8G8B8A8, /*!< ETC2 independent alpha. */
53 c_EAC_R11, /*!< R11 ETC2 single-channel. */
54 c_EAC_R11G11, /*!< R11G11 ETC2 dual-channel. */
55 c_ASTC, /*!< ASTC. */
56 c_ETC1S, /*!< ETC1S. */
57 c_PVRTC, /*!< PVRTC(1). */
58 c_PVRTC2 /*!< PVRTC2. */
59};
60
61typedef unsigned int uint32_t;
62
63#if !defined(LIBKTX)
64#include <vulkan/vulkan_core.h>
65#else
66#include "../vkformat_enum.h"
67#endif
68
69uint32_t* vk2dfd(enum VkFormat format);
70
71/* Create a Data Format Descriptor for an unpacked format. */
72uint32_t *createDFDUnpacked(int bigEndian, int numChannels, int bytes,
73 int redBlueSwap, enum VkSuffix suffix);
74
75/* Create a Data Format Descriptor for a packed format. */
76uint32_t *createDFDPacked(int bigEndian, int numChannels,
77 int bits[], int channels[],
78 enum VkSuffix suffix);
79
80/* Create a Data Format Descriptor for a compressed format. */
81uint32_t *createDFDCompressed(enum VkCompScheme compScheme,
82 int bwidth, int bheight, int bdepth,
83 enum VkSuffix suffix);
84
85/* Create a Data Format Descriptor for a depth/stencil format. */
86uint32_t *createDFDDepthStencil(int depthBits,
87 int stencilBits,
88 int sizeBytes);
89
90/** @brief Result of interpreting the data format descriptor. */
91enum InterpretDFDResult {
92 i_LITTLE_ENDIAN_FORMAT_BIT = 0, /*!< Confirmed little-endian (default for 8bpc). */
93 i_BIG_ENDIAN_FORMAT_BIT = 1, /*!< Confirmed big-endian. */
94 i_PACKED_FORMAT_BIT = 2, /*!< Packed format. */
95 i_SRGB_FORMAT_BIT = 4, /*!< sRGB transfer function. */
96 i_NORMALIZED_FORMAT_BIT = 8, /*!< Normalized (UNORM or SNORM). */
97 i_SIGNED_FORMAT_BIT = 16, /*!< Format is signed. */
98 i_FLOAT_FORMAT_BIT = 32, /*!< Format is floating point. */
99 i_UNSUPPORTED_ERROR_BIT = 64, /*!< Format not successfully interpreted. */
100 /** "NONTRIVIAL_ENDIANNESS" means not big-endian, not little-endian
101 * (a channel has bits that are not consecutive in either order). **/
102 i_UNSUPPORTED_NONTRIVIAL_ENDIANNESS = i_UNSUPPORTED_ERROR_BIT,
103 /** "MULTIPLE_SAMPLE_LOCATIONS" is an error because only single-sample
104 * texel blocks (with coordinates 0,0,0,0 for all samples) are supported. **/
105 i_UNSUPPORTED_MULTIPLE_SAMPLE_LOCATIONS = i_UNSUPPORTED_ERROR_BIT + 1,
106 /** "MULTIPLE_PLANES" is an error because only contiguous data is supported. */
107 i_UNSUPPORTED_MULTIPLE_PLANES = i_UNSUPPORTED_ERROR_BIT + 2,
108 /** Only channels R, G, B and A are supported. */
109 i_UNSUPPORTED_CHANNEL_TYPES = i_UNSUPPORTED_ERROR_BIT + 3,
110 /** Only channels with the same flags are supported
111 * (e.g. we don't support float red with integer green). */
112 i_UNSUPPORTED_MIXED_CHANNELS = i_UNSUPPORTED_ERROR_BIT + 4
113};
114
115/** @brief Interpretation of a channel from the data format descriptor. */
116typedef struct _InterpretedDFDChannel {
117 uint32_t offset; /*!< Offset in bits for packed, bytes for unpacked. */
118 uint32_t size; /*!< Size in bits for packed, bytes for unpacked. */
119} InterpretedDFDChannel;
120
121/* Interpret a Data Format Descriptor. */
122enum InterpretDFDResult interpretDFD(const uint32_t *DFD,
123 InterpretedDFDChannel *R,
124 InterpretedDFDChannel *G,
125 InterpretedDFDChannel *B,
126 InterpretedDFDChannel *A,
127 uint32_t *wordBytes);
128
129/* Print a human-readable interpretation of a data format descriptor. */
130void printDFD(uint32_t *DFD);
131
132/* Get the number of components & component size from a DFD for an
133 * unpacked format.
134 */
135void
136getDFDComponentInfoUnpacked(const uint32_t* DFD, uint32_t* numComponents,
137 uint32_t* componentByteLength);
138
139/* Return the number of components described by a DFD. */
140uint32_t getDFDNumComponents(const uint32_t* DFD);
141
142/* Recreate and return the value of bytesPlane0 as it should be for the data
143 * post-inflation from variable-rate compression.
144 */
145void
146recreateBytesPlane0FromSampleInfo(const uint32_t* DFD, uint32_t* bytesPlane0);
147
148/** @brief Colourspace primaries information.
149 *
150 * Structure to store the 1931 CIE x,y chromaticities of the red, green, and blue
151 * display primaries and the reference white point of a colourspace.
152 */
153typedef struct _Primaries {
154 float Rx; /*!< Red x. */
155 float Ry; /*!< Red y. */
156 float Gx; /*!< Green x. */
157 float Gy; /*!< Green y. */
158 float Bx; /*!< Blue x. */
159 float By; /*!< Blue y. */
160 float Wx; /*!< White x. */
161 float Wy; /*!< White y. */
162} Primaries;
163
164khr_df_primaries_e findMapping(Primaries *p, float latitude);
165
166#ifdef __cplusplus
167}
168#endif
169
170#endif /* _DFD_H_ */
171