357 lines
14 KiB
C++
357 lines
14 KiB
C++
// Copyright Epic Games, Inc. All Rights Reserved.
|
|
#pragma once
|
|
#include "Containers/Array.h"
|
|
#include "Containers/ContainersFwd.h"
|
|
#include "CoreTypes.h"
|
|
#include "ImageCore.h"
|
|
#include "Math/Color.h"
|
|
|
|
// This is supposed to be, as close as possible, the complete list of DXGI formats
|
|
// per those docs - the ODDFMTs we don't support for doing anything other than name, but we keep
|
|
// them here so we can stay in sync with the docs more easily.
|
|
//
|
|
// we support nope out on some of the more exotic formats entirely where they're unlikely
|
|
// to be useful for any assets
|
|
//
|
|
// fields: name, ID, bytes per unit (unit=1 texel for RGB, 1 block for BCN)
|
|
#define UE_DXGI_FORMAT_LIST \
|
|
RGBFMT(UNKNOWN, 0, 0) \
|
|
RGBFMT(R32G32B32A32_TYPELESS, 1, 16) \
|
|
RGBFMT(R32G32B32A32_FLOAT, 2, 16) \
|
|
RGBFMT(R32G32B32A32_UINT, 3, 16) \
|
|
RGBFMT(R32G32B32A32_SINT, 4, 16) \
|
|
RGBFMT(R32G32B32_TYPELESS, 5, 12) \
|
|
RGBFMT(R32G32B32_FLOAT, 6, 12) \
|
|
RGBFMT(R32G32B32_UINT, 7, 12) \
|
|
RGBFMT(R32G32B32_SINT, 8, 12) \
|
|
RGBFMT(R16G16B16A16_TYPELESS, 9, 8) \
|
|
RGBFMT(R16G16B16A16_FLOAT, 10, 8) \
|
|
RGBFMT(R16G16B16A16_UNORM, 11, 8) \
|
|
RGBFMT(R16G16B16A16_UINT, 12, 8) \
|
|
RGBFMT(R16G16B16A16_SNORM, 13, 8) \
|
|
RGBFMT(R16G16B16A16_SINT, 14, 8) \
|
|
RGBFMT(R32G32_TYPELESS, 15, 8) \
|
|
RGBFMT(R32G32_FLOAT, 16, 8) \
|
|
RGBFMT(R32G32_UINT, 17, 8) \
|
|
RGBFMT(R32G32_SINT, 18, 8) \
|
|
RGBFMT(R32G8X24_TYPELESS, 19, 8) \
|
|
RGBFMT(D32_FLOAT_S8X24_UINT, 20, 8) \
|
|
RGBFMT(R32_FLOAT_X8X24_TYPELESS, 21, 8) \
|
|
RGBFMT(X32_TYPELESS_G8X24_UINT, 22, 8) \
|
|
RGBFMT(R10G10B10A2_TYPELESS, 23, 4) \
|
|
RGBFMT(R10G10B10A2_UNORM, 24, 4) \
|
|
RGBFMT(R10G10B10A2_UINT, 25, 4) \
|
|
RGBFMT(R11G11B10_FLOAT, 26, 4) \
|
|
RGBFMT(R8G8B8A8_TYPELESS, 27, 4) \
|
|
RGBFMT(R8G8B8A8_UNORM, 28, 4) \
|
|
RGBFMT(R8G8B8A8_UNORM_SRGB, 29, 4) \
|
|
RGBFMT(R8G8B8A8_UINT, 30, 4) \
|
|
RGBFMT(R8G8B8A8_SNORM, 31, 4) \
|
|
RGBFMT(R8G8B8A8_SINT, 32, 4) \
|
|
RGBFMT(R16G16_TYPELESS, 33, 4) \
|
|
RGBFMT(R16G16_FLOAT, 34, 4) \
|
|
RGBFMT(R16G16_UNORM, 35, 4) \
|
|
RGBFMT(R16G16_UINT, 36, 4) \
|
|
RGBFMT(R16G16_SNORM, 37, 4) \
|
|
RGBFMT(R16G16_SINT, 38, 4) \
|
|
RGBFMT(R32_TYPELESS, 39, 4) \
|
|
RGBFMT(D32_FLOAT, 40, 4) \
|
|
RGBFMT(R32_FLOAT, 41, 4) \
|
|
RGBFMT(R32_UINT, 42, 4) \
|
|
RGBFMT(R32_SINT, 43, 4) \
|
|
RGBFMT(R24G8_TYPELESS, 44, 4) \
|
|
RGBFMT(D24_UNORM_S8_UINT, 45, 4) \
|
|
RGBFMT(R24_UNORM_X8_TYPELESS, 46, 4) \
|
|
RGBFMT(X24_TYPELESS_G8_UINT, 47, 4) \
|
|
RGBFMT(R8G8_TYPELESS, 48, 2) \
|
|
RGBFMT(R8G8_UNORM, 49, 2) \
|
|
RGBFMT(R8G8_UINT, 50, 2) \
|
|
RGBFMT(R8G8_SNORM, 51, 2) \
|
|
RGBFMT(R8G8_SINT, 52, 2) \
|
|
RGBFMT(R16_TYPELESS, 53, 2) \
|
|
RGBFMT(R16_FLOAT, 54, 2) \
|
|
RGBFMT(D16_UNORM, 55, 2) \
|
|
RGBFMT(R16_UNORM, 56, 2) \
|
|
RGBFMT(R16_UINT, 57, 2) \
|
|
RGBFMT(R16_SNORM, 58, 2) \
|
|
RGBFMT(R16_SINT, 59, 2) \
|
|
RGBFMT(R8_TYPELESS, 60, 1) \
|
|
RGBFMT(R8_UNORM, 61, 1) \
|
|
RGBFMT(R8_UINT, 62, 1) \
|
|
RGBFMT(R8_SNORM, 63, 1) \
|
|
RGBFMT(R8_SINT, 64, 1) \
|
|
RGBFMT(A8_UNORM, 65, 1) \
|
|
ODDFMT(R1_UNORM, 66) \
|
|
RGBFMT(R9G9B9E5_SHAREDEXP, 67, 4) \
|
|
ODDFMT(R8G8_B8G8_UNORM, 68) \
|
|
ODDFMT(G8R8_G8B8_UNORM, 69) \
|
|
BCNFMT(BC1_TYPELESS, 70, 8) \
|
|
BCNFMT(BC1_UNORM, 71, 8) \
|
|
BCNFMT(BC1_UNORM_SRGB, 72, 8) \
|
|
BCNFMT(BC2_TYPELESS, 73, 16) \
|
|
BCNFMT(BC2_UNORM, 74, 16) \
|
|
BCNFMT(BC2_UNORM_SRGB, 75, 16) \
|
|
BCNFMT(BC3_TYPELESS, 76, 16) \
|
|
BCNFMT(BC3_UNORM, 77, 16) \
|
|
BCNFMT(BC3_UNORM_SRGB, 78, 16) \
|
|
BCNFMT(BC4_TYPELESS, 79, 8) \
|
|
BCNFMT(BC4_UNORM, 80, 8) \
|
|
BCNFMT(BC4_SNORM, 81, 8) \
|
|
BCNFMT(BC5_TYPELESS, 82, 16) \
|
|
BCNFMT(BC5_UNORM, 83, 16) \
|
|
BCNFMT(BC5_SNORM, 84, 16) \
|
|
RGBFMT(B5G6R5_UNORM, 85, 2) \
|
|
RGBFMT(B5G5R5A1_UNORM, 86, 2) \
|
|
RGBFMT(B8G8R8A8_UNORM, 87, 4) \
|
|
RGBFMT(B8G8R8X8_UNORM, 88, 4) \
|
|
RGBFMT(R10G10B10_XR_BIAS_A2_UNORM, 89, 4) \
|
|
RGBFMT(B8G8R8A8_TYPELESS, 90, 4) \
|
|
RGBFMT(B8G8R8A8_UNORM_SRGB, 91, 4) \
|
|
RGBFMT(B8G8R8X8_TYPELESS, 92, 4) \
|
|
RGBFMT(B8G8R8X8_UNORM_SRGB, 93, 4) \
|
|
BCNFMT(BC6H_TYPELESS, 94, 16) \
|
|
BCNFMT(BC6H_UF16, 95, 16) \
|
|
BCNFMT(BC6H_SF16, 96, 16) \
|
|
BCNFMT(BC7_TYPELESS, 97, 16) \
|
|
BCNFMT(BC7_UNORM, 98, 16) \
|
|
BCNFMT(BC7_UNORM_SRGB, 99, 16) \
|
|
ODDFMT(AYUV, 100) \
|
|
ODDFMT(Y410, 101) \
|
|
ODDFMT(Y416, 102) \
|
|
ODDFMT(NV12, 103) \
|
|
ODDFMT(P010, 104) \
|
|
ODDFMT(P016, 105) \
|
|
ODDFMT(_420_OPAQUE, 106) \
|
|
ODDFMT(YUY2, 107) \
|
|
ODDFMT(Y210, 108) \
|
|
ODDFMT(Y216, 109) \
|
|
ODDFMT(NV11, 110) \
|
|
ODDFMT(AI44, 111) \
|
|
ODDFMT(IA44, 112) \
|
|
ODDFMT(P8, 113) \
|
|
ODDFMT(A8P8, 114) \
|
|
RGBFMT(B4G4R4A4_UNORM, 115,2) \
|
|
ODDFMT(P208, 130) \
|
|
ODDFMT(V208, 131) \
|
|
ODDFMT(V408, 132) \
|
|
RGBFMT(B8G8R8, 1001,3) \
|
|
RGBFMT(R8G8B8, 1002,3) \
|
|
RGBFMT(R8G8B8X8, 1003,4) \
|
|
/* end */
|
|
|
|
namespace UE { namespace DDS
|
|
{
|
|
// Complete list of formats
|
|
enum class EDXGIFormat
|
|
{
|
|
#define RGBFMT(name,id,bypu) name = id,
|
|
#define BCNFMT(name,id,bypu) name = id,
|
|
#define ODDFMT(name,id) name = id,
|
|
UE_DXGI_FORMAT_LIST
|
|
#undef RGBFMT
|
|
#undef BCNFMT
|
|
#undef ODDFMT
|
|
};
|
|
|
|
// What version of DDS file to write
|
|
enum class EDDSFormatVersion
|
|
{
|
|
Auto, // Write as D3D9-version DDS if possible without losing metadata like sRGB status, D3D10 otherwise
|
|
D3D9, // Try really hard to write a D3D9-format .DDS file (the more widely supported version) even when doing so loses some information
|
|
D3D10, // Always write a D3D10-format .DDS file
|
|
};
|
|
|
|
// Mip data read modes
|
|
enum class EDDSReadMipMode
|
|
{
|
|
Full,
|
|
HeaderOnly,
|
|
HeaderWithMipInfo,
|
|
};
|
|
|
|
// Error codes
|
|
enum class EDDSError
|
|
{
|
|
OK, // No error
|
|
Ok = OK,
|
|
OutOfMemory, // Out of memory/allocation failure while reading
|
|
NotADds, // No valid DDS header found
|
|
NotADDS = NotADds,
|
|
BadResourceDimension, // Resource not 1D, 2D or 3D
|
|
BadPixelFormat, // Malformed or unsupported pixel format
|
|
BadImageDimension, // Image dimensions (width, height, depth, array size) outside supported range
|
|
BadMipmapCount, // Invalid mipmap count for given image dimensions
|
|
BadCubemap, // Cubemap has non-square faces, non-1 depth, or unsupported array count
|
|
IoError, // General I/O error
|
|
};
|
|
|
|
// Channel ordering for 8-bit formats
|
|
enum class EChannelOrder
|
|
{
|
|
RGBA,
|
|
BGRA
|
|
};
|
|
|
|
// One of these for each mip of a DDS
|
|
struct FDDSMip
|
|
{
|
|
uint32 Width, Height, Depth;
|
|
// Note: pixels in DDS data must be densely packed, they exist for ease of addressing
|
|
// but you can't represent strided data in this form.
|
|
int64 RowStride; // Bytes in one row of a 2d slice of the mip. equal to SliceStride for 1D textures.
|
|
int64 SliceStride; // Bytes in one 2d slice of the mip, equal to DataStride for 2D textures.
|
|
int64 DataSize;
|
|
uint8* Data; // just raw bytes; interpretation as per DXGIFormat in parent FDDSFile
|
|
};
|
|
|
|
// Metadata structure for a DDS file, with access pointers for the raw texture data (i.e.
|
|
// unconverted from the DXGI format).
|
|
//
|
|
// Can be used for loading or saving a dds file.
|
|
//
|
|
// For saving, general structure is:
|
|
// {
|
|
// dds = FDDSFile::CreateEmpty[2D](...)
|
|
// copy data for each mip/array:
|
|
// for (mips)
|
|
// memcpy(dds->mips[idx].data, mip_data, mip_size);
|
|
//
|
|
// Ar = IFileManager::Get().CreateFileWriter(filename);
|
|
//
|
|
// dds->Serialize(Ar);
|
|
// delete dds;
|
|
//
|
|
// Ar->Close()
|
|
// delete Ar;
|
|
// }
|
|
struct FDDSFile
|
|
{
|
|
int32 Dimension=0; // 1, 2 or 3.
|
|
uint32 Width=0;
|
|
uint32 Height=0;
|
|
uint32 Depth=0;
|
|
uint32 MipCount=0;
|
|
|
|
// Array size here uses the conventions as in the D3D runtime, which means
|
|
// an array of N cubemaps has an array size of 6N (one element per face).
|
|
uint32 ArraySize=0;
|
|
EDXGIFormat DXGIFormat=EDXGIFormat::UNKNOWN;
|
|
uint32 CreateFlags=0;
|
|
|
|
// Mips are ordered starting from mip 0 (full-size texture) decreasing in size;
|
|
// for arrays, we store the full mip chain for one array element before advancing
|
|
// to the next array element, and have (ArraySize * MipCount) mips total.
|
|
TArray<FDDSMip> Mips;
|
|
|
|
// When we allocate the mips ourselves, we keep all storage together in a single
|
|
// allocation, namely this one, and the mips point into it.
|
|
// With CREATE_FLAG_NO_MIP_STORAGE_ALLOC, we don't own the underlying memory and
|
|
// this array is unused.
|
|
TArray64<uint8> MipRawData;
|
|
|
|
// Write DDS-format data to memory. This produces a memory image of a DDS file.
|
|
//
|
|
// Automatic format selection rules used are:
|
|
// - D3D9 DDS does not support 1D or array textures directly, so these always write as D3D10
|
|
// - The pixel format must be a "common" D3D9 format (more obscure formats can be used for D3D9
|
|
// writing when InFormatVersion is D3D9, but "Auto" sticks with a restricted subset)
|
|
// - For 8-bit pixel formats, the format must be non-sRGB.
|
|
//
|
|
// The latter is somewhat arbitrary. D3D9 DDS files don't store whether pixels for a texture are meant
|
|
// to be interpreted as sRGB or not. This reader treats the resulting formats as non-sRGB UNORM,
|
|
// so the writer does the same for symmetry.
|
|
IMAGECORE_API EDDSError WriteDDS(TArray64<uint8>& OutDDS, EDDSFormatVersion InFormatVersion=EDDSFormatVersion::D3D10);
|
|
|
|
// 20 mips means 512k x 512k pixels max, should be sufficient for now.
|
|
// It's 512k not 1M because the final 1x1 pixel mip counts; i.e. a mip chain
|
|
// from 1048576x1048576 down to 1x1 has 21 mips!
|
|
static constexpr uint32 MAX_MIPS_SUPPORTED = 20;
|
|
|
|
// Create an empty DDS structure (for writing DDS files typically)
|
|
//
|
|
// InDimension is [1,3] (1D,2D,3D)
|
|
// InWidth/InHeight are for the top mip. Cubemaps must be square.
|
|
// InDepth is only used for 3D textures, must be 1 otherwise.
|
|
// InMipCount <= MAX_MIPS_SUPPORTED.
|
|
// InArraySize number of textures provided - must be multiple of 6 for cubemaps (CREATE_FLAG_CUBEMAP)
|
|
//
|
|
// Note for texture arrays the mip data pointers are expecting the entire mip chain
|
|
// for one texture before moving to the next
|
|
//
|
|
// On error, returns nullptr. If a non-null OutError is supplied, error information
|
|
// is written there.
|
|
IMAGECORE_API static FDDSFile* CreateEmpty(int32 InDimension, uint32 InWidth, uint32 InHeight, uint32 InDepth, uint32 InMipCount, uint32 InArraySize, EDXGIFormat InFormat, uint32 InCreateFlags, EDDSError *OutError=nullptr);
|
|
|
|
// Convenience version of the above to create a basic 2D texture with mip chain
|
|
IMAGECORE_API static FDDSFile* CreateEmpty2D(uint32 InWidth, uint32 InHeight, uint32 InMipCount, EDXGIFormat InFormat, uint32 InCreateFlags, EDDSError* OutError=nullptr);
|
|
|
|
// Sanity-check that all members make sense and return an error code.
|
|
IMAGECORE_API EDDSError Validate() const;
|
|
|
|
// Check if this DDS is usable in Unreal Texture types:
|
|
IMAGECORE_API bool IsValidTexture2D() const;
|
|
IMAGECORE_API bool IsValidTextureCube() const; // or cube array
|
|
IMAGECORE_API bool IsValidTextureArray() const;
|
|
IMAGECORE_API bool IsValidTextureVolume() const;
|
|
|
|
UE_DEPRECATED(5.6, "This function is now deprecated, please use CreateFromDDSInMemory with EDDSReadMipMode instead.")
|
|
IMAGECORE_API static FDDSFile* CreateFromDDSInMemory(const uint8* InDDS, int64 InDDSSize, EDDSError* OutError, bool bHeaderOnly);
|
|
|
|
// Used for loading from a DDS file image in memory.
|
|
//
|
|
// On error, returns nullptr. If a non-null OutError is supplied, error information
|
|
// is written there.
|
|
IMAGECORE_API static FDDSFile* CreateFromDDSInMemory(const uint8* InDDS, int64 InDDSSize, EDDSError* OutError=nullptr, EDDSReadMipMode InMipReadMode = EDDSReadMipMode::Full);
|
|
|
|
// is this buffer a DDS ?
|
|
IMAGECORE_API static bool IsADDS(const uint8* InDDS, int64 InDDSSize);
|
|
|
|
// For 8-bit UNorm formats, both RGBA and BGRA channel order variants exist and
|
|
// are popular. This function does the trivial conversion between the two, updating
|
|
// both the DXGI Format and the pixel data to do so. When the channel order is already
|
|
// correct or the pixel format is not one of the few formats that exist in both RGBA
|
|
// and BGRA variants, this function does nothing.
|
|
IMAGECORE_API void ConvertChannelOrder(EChannelOrder InTargetOrder);
|
|
|
|
// convert X alpha to A and fill 255
|
|
IMAGECORE_API void ConvertRGBXtoRGBA();
|
|
|
|
// Blit pixels from DDS mip to Image
|
|
// return false if no pixel format conversion is supported
|
|
// ToImage is not allocated, must be pre-allocated and sized correctly
|
|
IMAGECORE_API bool GetMipImage(const FImageView & ToImage, int MipIndex) const;
|
|
|
|
// Fill DDS mip from Image
|
|
// Image must be of format DXGIFormatFromRawFormat
|
|
IMAGECORE_API void FillMip(const FImageView & FromImage, int MipIndex);
|
|
|
|
// Bit flags
|
|
static constexpr uint32 CREATE_FLAG_NONE = 0;
|
|
static constexpr uint32 CREATE_FLAG_CUBEMAP = 1;
|
|
static constexpr uint32 CREATE_FLAG_NO_MIP_STORAGE_ALLOC = 2; // Mip storage wasn't allocated by us and isn't owned by us, just pointing elsewhere.
|
|
static constexpr uint32 CREATE_FLAG_WAS_D3D9 = 4; // Loaded from D3D9-format .DDS file, so whether 8-bit/channel formats are sRGB or not is largely guesswork
|
|
};
|
|
|
|
// Returns the name of a DXGI format
|
|
IMAGECORE_API const TCHAR *DXGIFormatGetName(EDXGIFormat InFormat);
|
|
|
|
// Returns whether a given pixel format is sRGB
|
|
IMAGECORE_API bool DXGIFormatIsSRGB(EDXGIFormat InFormat);
|
|
IMAGECORE_API bool DXGIFormatHasLinearAndSRGBForm(EDXGIFormat InFormat);
|
|
|
|
// Return the corresponding non-sRGB version of a pixel format if there is one
|
|
IMAGECORE_API EDXGIFormat DXGIFormatRemoveSRGB(EDXGIFormat InFormat);
|
|
|
|
// Return the corresponding sRGB version of a pixel format if there is one
|
|
IMAGECORE_API EDXGIFormat DXGIFormatAddSRGB(EDXGIFormat InFormat);
|
|
|
|
IMAGECORE_API EDXGIFormat DXGIFormatFromRawFormat(ERawImageFormat::Type RawFormat,EGammaSpace GammaSpace);
|
|
|
|
IMAGECORE_API ERawImageFormat::Type DXGIFormatGetClosestRawFormat(EDXGIFormat fmt, bool * pIsExactMatch = nullptr);
|
|
|
|
// note these sizes include the 4-byte magic word, unlike the older DDSLoader functions
|
|
IMAGECORE_API int64 GetDDSHeaderMaximalSize();
|
|
IMAGECORE_API int64 GetDDSHeaderMinimalSize();
|
|
|
|
} }
|