1// basis_file_headers.h
2// Copyright (C) 2019-2020 Binomial LLC. All Rights Reserved.
3//
4// Licensed under the Apache License, Version 2.0 (the "License");
5// you may not use this file except in compliance with the License.
6// You may obtain a copy of the License at
7//
8// http://www.apache.org/licenses/LICENSE-2.0
9//
10// Unless required by applicable law or agreed to in writing, software
11// distributed under the License is distributed on an "AS IS" BASIS,
12// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13// See the License for the specific language governing permissions and
14// limitations under the License.
15#pragma once
16#include "basisu_transcoder_internal.h"
17
18namespace basist
19{
20 // Slice desc header flags
21 enum basis_slice_desc_flags
22 {
23 cSliceDescFlagsHasAlpha = 1,
24
25 // Video only: Frame doesn't refer to previous frame (no usage of conditional replenishment pred symbols)
26 // Currently the first frame is always an I-Frame, all subsequent frames are P-Frames. This will eventually be changed to periodic I-Frames.
27 cSliceDescFlagsFrameIsIFrame = 2
28 };
29
30#pragma pack(push)
31#pragma pack(1)
32 struct basis_slice_desc
33 {
34 basisu::packed_uint<3> m_image_index; // The index of the source image provided to the encoder (will always appear in order from first to last, first image index is 0, no skipping allowed)
35 basisu::packed_uint<1> m_level_index; // The mipmap level index (mipmaps will always appear from largest to smallest)
36 basisu::packed_uint<1> m_flags; // enum basis_slice_desc_flags
37
38 basisu::packed_uint<2> m_orig_width; // The original image width (may not be a multiple of 4 pixels)
39 basisu::packed_uint<2> m_orig_height; // The original image height (may not be a multiple of 4 pixels)
40
41 basisu::packed_uint<2> m_num_blocks_x; // The slice's block X dimensions. Each block is 4x4 pixels. The slice's pixel resolution may or may not be a power of 2.
42 basisu::packed_uint<2> m_num_blocks_y; // The slice's block Y dimensions.
43
44 basisu::packed_uint<4> m_file_ofs; // Offset from the start of the file to the start of the slice's data
45 basisu::packed_uint<4> m_file_size; // The size of the compressed slice data in bytes
46
47 basisu::packed_uint<2> m_slice_data_crc16; // The CRC16 of the compressed slice data, for extra-paranoid use cases
48 };
49
50 // File header files
51 enum basis_header_flags
52 {
53 // Always set for ETC1S files. Not set for UASTC files.
54 cBASISHeaderFlagETC1S = 1,
55
56 // Set if the texture had to be Y flipped before encoding. The actual interpretation of this (is Y up or down?) is up to the user.
57 cBASISHeaderFlagYFlipped = 2,
58
59 // Set if any slices contain alpha (for ETC1S, if the odd slices contain alpha data)
60 cBASISHeaderFlagHasAlphaSlices = 4,
61
62 // For ETC1S files, this will be true if the file utilizes a codebook from another .basis file.
63 cBASISHeaderFlagUsesGlobalCodebook = 8,
64
65 // Set if the texture data is sRGB, otherwise it's linear.
66 // In reality, we have no idea if the texture data is actually linear or sRGB. This is the m_perceptual parameter passed to the compressor.
67 cBASISHeaderFlagSRGB = 16,
68 };
69
70 // The image type field attempts to describe how to interpret the image data in a Basis file.
71 // The encoder library doesn't really do anything special or different with these texture types, this is mostly here for the benefit of the user.
72 // We do make sure the various constraints are followed (2DArray/cubemap/videoframes/volume implies that each image has the same resolution and # of mipmap levels, etc., cubemap implies that the # of image slices is a multiple of 6)
73 enum basis_texture_type
74 {
75 cBASISTexType2D = 0, // An arbitrary array of 2D RGB or RGBA images with optional mipmaps, array size = # images, each image may have a different resolution and # of mipmap levels
76 cBASISTexType2DArray = 1, // An array of 2D RGB or RGBA images with optional mipmaps, array size = # images, each image has the same resolution and mipmap levels
77 cBASISTexTypeCubemapArray = 2, // an array of cubemap levels, total # of images must be divisable by 6, in X+, X-, Y+, Y-, Z+, Z- order, with optional mipmaps
78 cBASISTexTypeVideoFrames = 3, // An array of 2D video frames, with optional mipmaps, # frames = # images, each image has the same resolution and # of mipmap levels
79 cBASISTexTypeVolume = 4, // A 3D texture with optional mipmaps, Z dimension = # images, each image has the same resolution and # of mipmap levels
80
81 cBASISTexTypeTotal
82 };
83
84 enum
85 {
86 cBASISMaxUSPerFrame = 0xFFFFFF
87 };
88
89 enum class basis_tex_format
90 {
91 cETC1S = 0,
92 cUASTC4x4 = 1
93 };
94
95 struct basis_file_header
96 {
97 enum
98 {
99 cBASISSigValue = ('B' << 8) | 's',
100 cBASISFirstVersion = 0x10
101 };
102
103 basisu::packed_uint<2> m_sig; // 2 byte file signature
104 basisu::packed_uint<2> m_ver; // Baseline file version
105 basisu::packed_uint<2> m_header_size; // Header size in bytes, sizeof(basis_file_header)
106 basisu::packed_uint<2> m_header_crc16; // CRC16 of the remaining header data
107
108 basisu::packed_uint<4> m_data_size; // The total size of all data after the header
109 basisu::packed_uint<2> m_data_crc16; // The CRC16 of all data after the header
110
111 basisu::packed_uint<3> m_total_slices; // The total # of compressed slices (1 slice per image, or 2 for alpha .basis files)
112
113 basisu::packed_uint<3> m_total_images; // The total # of images
114
115 basisu::packed_uint<1> m_tex_format; // enum basis_tex_format
116 basisu::packed_uint<2> m_flags; // enum basist::header_flags
117 basisu::packed_uint<1> m_tex_type; // enum basist::basis_texture_type
118 basisu::packed_uint<3> m_us_per_frame; // Framerate of video, in microseconds per frame
119
120 basisu::packed_uint<4> m_reserved; // For future use
121 basisu::packed_uint<4> m_userdata0; // For client use
122 basisu::packed_uint<4> m_userdata1; // For client use
123
124 basisu::packed_uint<2> m_total_endpoints; // The number of endpoints in the endpoint codebook
125 basisu::packed_uint<4> m_endpoint_cb_file_ofs; // The compressed endpoint codebook's file offset relative to the start of the file
126 basisu::packed_uint<3> m_endpoint_cb_file_size; // The compressed endpoint codebook's size in bytes
127
128 basisu::packed_uint<2> m_total_selectors; // The number of selectors in the endpoint codebook
129 basisu::packed_uint<4> m_selector_cb_file_ofs; // The compressed selectors codebook's file offset relative to the start of the file
130 basisu::packed_uint<3> m_selector_cb_file_size; // The compressed selector codebook's size in bytes
131
132 basisu::packed_uint<4> m_tables_file_ofs; // The file offset of the compressed Huffman codelength tables, for decompressing slices
133 basisu::packed_uint<4> m_tables_file_size; // The file size in bytes of the compressed huffman codelength tables
134
135 basisu::packed_uint<4> m_slice_desc_file_ofs; // The file offset to the slice description array, usually follows the header
136
137 basisu::packed_uint<4> m_extended_file_ofs; // The file offset of the "extended" header and compressed data, for future use
138 basisu::packed_uint<4> m_extended_file_size; // The file size in bytes of the "extended" header and compressed data, for future use
139 };
140#pragma pack (pop)
141
142} // namespace basist
143