Blender V5.3
format_dds.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2009 Google Inc. All rights reserved. (BSD-3-Clause)
2 * SPDX-FileCopyrightText: 2023-2024 Blender Authors (GPL-2.0-or-later).
3 *
4 * SPDX-License-Identifier: GPL-2.0-or-later AND BSD-3-Clause */
5
12
13#include <algorithm>
14#include <fcntl.h>
15#if defined(WIN32)
16# include <io.h>
17#else
18# include <unistd.h>
19#endif
20
22
23#include "IMB_filetype.hh"
24#include "IMB_imbuf_types.hh"
25
26#include "BLI_fileops.hh"
27#include "BLI_math_base_c.hh"
28#include "BLI_mmap.hh"
29#include "BLI_path_utils.hh"
30#include "BLI_string.hh"
31#include "MEM_guardedalloc.h"
32
33namespace blender {
34
35const char *imb_file_extensions_dds[] = {".dds", nullptr};
36
37OIIO_NAMESPACE_USING
38using namespace blender::imbuf;
39
41{
42 /* To match historical behavior for DDS file loading, tell OpenImageIO
43 * to process BC5 compressed textures as normal maps. But only do so
44 * if the environment does not already contain a directive that might
45 * say otherwise. */
46 const char *bc5normal = "dds:bc5normal";
47 const char *oiio_env = BLI_getenv("OPENIMAGEIO_OPTIONS");
48 if (!oiio_env || !BLI_strcasestr(oiio_env, bc5normal)) {
49 OIIO::attribute(bc5normal, 1);
50 }
51}
52
53bool imb_is_a_dds(const uchar *mem, size_t size)
54{
55 return imb_oiio_check(mem, size, "dds");
56}
57
59 size_t size,
60 ImBufFlags flags,
61 ImFileColorSpace &r_colorspace)
62{
63 ImageSpec config, spec;
64 ReadContext ctx{mem, size, "dds", IMB_FTYPE_DDS, flags};
65
66 ImBuf *ibuf = imb_oiio_read(ctx, config, r_colorspace, spec);
67 if (ibuf) {
68 std::string compression = spec.get_string_attribute("compression", "");
69 if (compression == "DXT1") {
71 }
72 if (compression == "DXT3") {
74 }
75 if (compression == "DXT5") {
77 }
78 }
79
80 return ibuf;
81}
82
83/* A function that flips a DXTC block. */
84using FlipBlockFunction = void (*)(uint8_t *block);
85
86/* Flips a full DXT1 block in the y direction. */
87static void FlipDXT1BlockFull(uint8_t *block)
88{
89 /* A DXT1 block layout is:
90 * [0-1] color0.
91 * [2-3] color1.
92 * [4-7] color bitmap, 2 bits per pixel.
93 * So each of the 4-7 bytes represents one line, flipping a block is just
94 * flipping those bytes. */
95 uint8_t tmp = block[4];
96 block[4] = block[7];
97 block[7] = tmp;
98 tmp = block[5];
99 block[5] = block[6];
100 block[6] = tmp;
101}
102
103/* Flips the first 2 lines of a DXT1 block in the y direction. */
104static void FlipDXT1BlockHalf(uint8_t *block)
105{
106 /* See layout above. */
107 uint8_t tmp = block[4];
108 block[4] = block[5];
109 block[5] = tmp;
110}
111
112/* Flips a full DXT3 block in the y direction. */
113static void FlipDXT3BlockFull(uint8_t *block)
114{
115 /* A DXT3 block layout is:
116 * [0-7] alpha bitmap, 4 bits per pixel.
117 * [8-15] a DXT1 block. */
118
119 /* We can flip the alpha bits at the byte level (2 bytes per line). */
120 uint8_t tmp = block[0];
121
122 block[0] = block[6];
123 block[6] = tmp;
124 tmp = block[1];
125 block[1] = block[7];
126 block[7] = tmp;
127 tmp = block[2];
128 block[2] = block[4];
129 block[4] = tmp;
130 tmp = block[3];
131 block[3] = block[5];
132 block[5] = tmp;
133
134 /* And flip the DXT1 block using the above function. */
135 FlipDXT1BlockFull(block + 8);
136}
137
138/* Flips the first 2 lines of a DXT3 block in the y direction. */
139static void FlipDXT3BlockHalf(uint8_t *block)
140{
141 /* See layout above. */
142 uint8_t tmp = block[0];
143
144 block[0] = block[2];
145 block[2] = tmp;
146 tmp = block[1];
147 block[1] = block[3];
148 block[3] = tmp;
149 FlipDXT1BlockHalf(block + 8);
150}
151
152/* Flips a full DXT5 block in the y direction. */
153static void FlipDXT5BlockFull(uint8_t *block)
154{
155 /* A DXT5 block layout is:
156 * [0] alpha0.
157 * [1] alpha1.
158 * [2-7] alpha bitmap, 3 bits per pixel.
159 * [8-15] a DXT1 block. */
160
161 /* The alpha bitmap doesn't easily map lines to bytes, so we have to
162 * interpret it correctly. Extracted from
163 * http://www.opengl.org/registry/specs/EXT/texture_compression_s3tc.txt :
164 *
165 * The 6 "bits" bytes of the block are decoded into one 48-bit integer:
166 *
167 * bits = bits_0 + 256 * (bits_1 + 256 * (bits_2 + 256 * (bits_3 +
168 * 256 * (bits_4 + 256 * bits_5))))
169 *
170 * bits is a 48-bit unsigned-integer, from which a three-bit control code
171 * is extracted for a texel at location (x,y) in the block using:
172 *
173 * code(x,y) = bits[3*(4*y+x)+1..3*(4*y+x)+0]
174 *
175 * where bit 47 is the most significant and bit 0 is the least
176 * significant bit. */
177 uint line_0_1 = block[2] + 256 * (block[3] + 256 * block[4]);
178 uint line_2_3 = block[5] + 256 * (block[6] + 256 * block[7]);
179 /* swap lines 0 and 1 in line_0_1. */
180 uint line_1_0 = ((line_0_1 & 0x000fff) << 12) | ((line_0_1 & 0xfff000) >> 12);
181 /* swap lines 2 and 3 in line_2_3. */
182 uint line_3_2 = ((line_2_3 & 0x000fff) << 12) | ((line_2_3 & 0xfff000) >> 12);
183
184 block[2] = line_3_2 & 0xff;
185 block[3] = (line_3_2 & 0xff00) >> 8;
186 block[4] = (line_3_2 & 0xff0000) >> 16;
187 block[5] = line_1_0 & 0xff;
188 block[6] = (line_1_0 & 0xff00) >> 8;
189 block[7] = (line_1_0 & 0xff0000) >> 16;
190
191 /* And flip the DXT1 block using the above function. */
192 FlipDXT1BlockFull(block + 8);
193}
194
195/* Flips the first 2 lines of a DXT5 block in the y direction. */
196static void FlipDXT5BlockHalf(uint8_t *block)
197{
198 /* See layout above. */
199 uint line_0_1 = block[2] + 256 * (block[3] + 256 * block[4]);
200 uint line_1_0 = ((line_0_1 & 0x000fff) << 12) | ((line_0_1 & 0xfff000) >> 12);
201 block[2] = line_1_0 & 0xff;
202 block[3] = (line_1_0 & 0xff00) >> 8;
203 block[4] = (line_1_0 & 0xff0000) >> 16;
204 FlipDXT1BlockHalf(block + 8);
205}
206
207static constexpr uint32_t fourcc_dxt1 = 0x31545844; /* D, X, T, 1 */
208static constexpr uint32_t fourcc_dxt3 = 0x33545844; /* D, X, T, 3 */
209static constexpr uint32_t fourcc_dxt5 = 0x35545844; /* D, X, T, 5 */
210
217 uint8_t *data, size_t data_size, int width, int height, int levels, uint32_t fourcc)
218{
219 /* Must have valid dimensions. */
220 if (width == 0 || height == 0) {
221 return 0;
222 }
223
224 /* Height must be a power-of-two: not because something within DXT/S3TC
225 * needs it. Only because we want to flip the image upside down, by
226 * swapping and flipping block rows, and that in general case (with mipmaps)
227 * is only possible for POT height. */
228 if (!is_power_of_2_i(height)) {
229 return 0;
230 }
231
232 FlipBlockFunction full_block_function;
233 FlipBlockFunction half_block_function;
234 size_t block_bytes = 0;
235
236 switch (fourcc) {
237 case fourcc_dxt1:
238 full_block_function = FlipDXT1BlockFull;
239 half_block_function = FlipDXT1BlockHalf;
240 block_bytes = 8;
241 break;
242 case fourcc_dxt3:
243 full_block_function = FlipDXT3BlockFull;
244 half_block_function = FlipDXT3BlockHalf;
245 block_bytes = 16;
246 break;
247 case fourcc_dxt5:
248 full_block_function = FlipDXT5BlockFull;
249 half_block_function = FlipDXT5BlockHalf;
250 block_bytes = 16;
251 break;
252 default:
253 return 0;
254 }
255
256 int mip_width = width;
257 int mip_height = height;
258
259 const uint8_t *data_end = data + data_size;
260
261 for (int level = 0; level < levels; level++) {
262 int blocks_per_row = (mip_width + 3) / 4;
263 int blocks_per_col = (mip_height + 3) / 4;
264 int blocks = blocks_per_row * blocks_per_col;
265
266 if (data + block_bytes * blocks > data_end) {
267 /* Stop flipping when running out of data to be modified, avoiding possible buffer overrun
268 * on a malformed files. */
269 return level;
270 }
271
272 if (mip_height == 1) {
273 /* no flip to do, and we're done. */
274 break;
275 }
276 if (mip_height == 2) {
277 /* flip the first 2 lines in each block. */
278 for (int i = 0; i < blocks_per_row; i++) {
279 half_block_function(data + i * block_bytes);
280 }
281 }
282 else {
283 /* flip each block. */
284 for (int i = 0; i < blocks; i++) {
285 full_block_function(data + i * block_bytes);
286 }
287
288 /* Swap each block line in the first half of the image with the
289 * corresponding one in the second half.
290 * note that this is a no-op if mip height is 4. */
291 size_t row_bytes = block_bytes * blocks_per_row;
292 uint8_t *temp_line = new uint8_t[row_bytes];
293
294 for (int y = 0; y < blocks_per_col / 2; y++) {
295 uint8_t *line1 = data + y * row_bytes;
296 uint8_t *line2 = data + (blocks_per_col - y - 1) * row_bytes;
297
298 memcpy(temp_line, line1, row_bytes);
299 memcpy(line1, line2, row_bytes);
300 memcpy(line2, temp_line, row_bytes);
301 }
302
303 delete[] temp_line;
304 }
305
306 /* Advance to next mip level. */
307 data += block_bytes * blocks;
308 mip_width = std::max(1, mip_width >> 1);
309 mip_height = std::max(1, mip_height >> 1);
310 }
311
312 return levels;
313}
314
315uint8_t *imb_load_dds_compressed_data(const char *filepath, int width, int height, int &r_mipcount)
316{
317 r_mipcount = 0;
318
319 /* Due to upside down flipping, we only support compressed DDS files with power of two heights.
320 */
321 if (!is_power_of_2_i(height)) {
322 return nullptr;
323 }
324
325 const int file = BLI_open(filepath, O_BINARY | O_RDONLY, 0);
326 if (file == -1) {
327 return nullptr;
328 }
329 BLI_mmap_file *mmap_file = BLI_mmap_open(file);
330 close(file);
331 if (mmap_file == nullptr) {
332 return nullptr;
333 }
334
335 uint8_t *result = nullptr;
336
337 const uchar *file_data = static_cast<const uchar *>(BLI_mmap_get_pointer(mmap_file));
338 const size_t file_size = BLI_mmap_get_length(mmap_file);
339
340 constexpr size_t dds_header_size = 128;
341 if (file_size < dds_header_size) {
342 BLI_mmap_free(mmap_file);
343 return nullptr;
344 }
345
346 /* Pull out pixel format and mipmap count flags from DDS header. */
347 uint32_t flags = 0, mipcount = 0, fourcc = 0;
348 memcpy(&flags, file_data + 8, 4);
349 memcpy(&mipcount, file_data + 28, 4);
350 memcpy(&fourcc, file_data + 84, 4);
351
352 /* Due to upside down flipping, we only support DXT1/DXT3/DXT5. Newer formats like BC7 can't
353 * be flipped upside down due to non-symmetrical partition shapes. */
354 if (ELEM(fourcc, fourcc_dxt1, fourcc_dxt3, fourcc_dxt5)) {
355
356 constexpr uint32_t DDSD_MIPMAPCOUNT = 0x00020000U;
357 if ((flags & DDSD_MIPMAPCOUNT) == 0) {
358 mipcount = 1;
359 }
360
361 size_t pixel_data_size = file_size - dds_header_size;
362
363 result = MEM_new_array_uninitialized<uint8_t>(pixel_data_size, "DDS compressed data");
364 memcpy(result, file_data + dds_header_size, pixel_data_size);
365
366 r_mipcount = flip_dxtc_image(result, pixel_data_size, width, height, mipcount, fourcc);
367 }
368
369 BLI_mmap_free(mmap_file);
370
371 return result;
372}
373
374} // namespace blender
File and directory operations.
#define O_BINARY
#define DDS_COMPRESSED_DXT3
#define DDS_COMPRESSED_DXT1
#define DDS_COMPRESSED_DXT5
Read Blender memory allocation and freeing.
#define ELEM(...)
ImBuf * imb_oiio_read(const ReadContext &ctx, const ImageSpec &config, ImFileColorSpace &r_colorspace, ImageSpec &r_newspec)
bool imb_oiio_check(const uchar *mem, size_t mem_size, const char *file_format)
BMesh Iterators.
unsigned int uint
Definition BKE_text.h:55
void * MEM_new_array_uninitialized(size_t len, size_t size, const char *str) ATTR_WARN_UNUSED_RESULT ATTR_ALLOC_SIZE(1
static constexpr uint32_t fourcc_dxt3
size_t BLI_mmap_get_length(const BLI_mmap_file *file) ATTR_WARN_UNUSED_RESULT
Definition BLI_mmap.cc:484
BLI_mmap_file * BLI_mmap_open(int fd) ATTR_MALLOC ATTR_WARN_UNUSED_RESULT
Definition BLI_mmap.cc:369
static constexpr uint32_t fourcc_dxt5
static void FlipDXT5BlockFull(uint8_t *block)
int BLI_open(const char *filepath, int oflag, int pmode) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL()
static int flip_dxtc_image(uint8_t *data, size_t data_size, int width, int height, int levels, uint32_t fourcc)
void BLI_mmap_free(BLI_mmap_file *file) ATTR_NONNULL(1)
Definition BLI_mmap.cc:494
void imb_init_dds()
Definition format_dds.cc:40
int char * BLI_strcasestr(const char *s, const char *find) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1
ImBuf * imb_load_dds(const uchar *mem, size_t size, ImBufFlags flags, ImFileColorSpace &r_colorspace)
Definition format_dds.cc:58
static void FlipDXT1BlockHalf(uint8_t *block)
unsigned int uint32_t
Definition BKE_text.h:81
unsigned char uchar
Definition BKE_text.h:58
uint8_t * imb_load_dds_compressed_data(const char *filepath, int width, int height, int &r_mipcount)
BMesh const char void * data
unsigned char uint8_t
Definition BKE_text.h:79
static void FlipDXT3BlockHalf(uint8_t *block)
static void FlipDXT1BlockFull(uint8_t *block)
Definition format_dds.cc:87
const char * imb_file_extensions_dds[]
Definition format_dds.cc:35
static void FlipDXT3BlockFull(uint8_t *block)
static void FlipDXT5BlockHalf(uint8_t *block)
bool imb_is_a_dds(const uchar *mem, size_t size)
Definition format_dds.cc:53
void * BLI_mmap_get_pointer(BLI_mmap_file *file) ATTR_WARN_UNUSED_RESULT
Definition BLI_mmap.cc:479
static constexpr uint32_t fourcc_dxt1
void(*)(uint8_t *block) FlipBlockFunction
Definition format_dds.cc:84
MINLINE int is_power_of_2_i(int n)
const char * BLI_getenv(const char *env) ATTR_NONNULL(1) ATTR_WARN_UNUSED_RESULT
ImbFormatOptions foptions