Textures

Typedefs

typedef BaseTexture Texture

typedef BaseTexture CubeTexture

typedef BaseTexture VolTexture

typedef BaseTexture ArrayTexture

typedef void (*on_tex_slice_loaded_cb_t)(): load texture content from DDSx stream using DDSx header for previously allocated texture

Enums

enum class ChannelDType : uint8_t

Values:

enumerator NONE

enumerator UNORM

enumerator SNORM

enumerator UFLOAT

enumerator SFLOAT

enumerator UINT

enumerator SINT

Values:

enumerator TEXLOCK_DISCARD

enumerator TEXLOCK_RAWDATA

enumerator TEXLOCK_NOSYSLOCK

enumerator TEXLOCK_READ

enumerator TEXLOCK_WRITE

enumerator TEXLOCK_READWRITE

enumerator TEXLOCK_RWMASK

enumerator TEXLOCK_DELSYSMEMCOPY

enumerator TEXLOCK_DONOTUPDATE

enumerator TEXLOCK_DEFAULT

Values:

enumerator TEXLF_CALCMIPMAPS

Values:

enumerator CUBEFACE_POSX

enumerator CUBEFACE_NEGX

enumerator CUBEFACE_POSY

enumerator CUBEFACE_NEGY

enumerator CUBEFACE_POSZ

enumerator CUBEFACE_NEGZ

enum class TexLoadRes

Values:

enumerator ERR

enumerator OK

enumerator ERR_RUB

Functions

bool is_alpha_texformat(unsigned flags)

bool is_bc_texformat(unsigned flags)

uint32_t auto_mip_levels_count(uint32_t w, uint32_t min_size)

uint32_t auto_mip_levels_count(uint32_t w, uint32_t h, uint32_t min_size)

uint32_t auto_mip_levels_count(uint32_t w, uint32_t h, uint32_t d, uint32_t min_size)

uint32_t parse_tex_format(const char *name, uint32_t default_fmt)

const TextureFormatDesc &get_tex_format_desc(uint32_t fmt)

const char *get_tex_format_name(uint32_t fmt)

uint32_t get_tex_channel_value(const void *pixel, const TextureChannelFormatDesc &channel)

Extracts a the bits from a pixel at memory location pixel that correspond to a particular channel in the specified format.

Note

Bits unused by the channel are set to 0, even for signed formats

Warning

This is extremely slow!

Parameters:

pixel – Memory location of the pixel
channel – Description of the channel’s format

Returns:

A uint32_t whose lowest bits contain the bits of the channel

void set_tex_channel_value(void *pixel, const TextureChannelFormatDesc &channel, uint32_t bits)

Sets the bits for a pixel at memory location pixel that correspond to a particular channel in the specified format.

Warning

This is extremely slow!

Parameters:

pixel – Memory location of the pixel
channel – Description of the channel’s format
bits – The bits to assign to the channel (only the lowest bits are used)

float channel_bits_to_float(uint32_t bits, ChannelDType type, const TextureChannelFormatDesc &channel)

Converts raw bits of a channel in a certain format into a floating point value that matches the logical value of the channel as closely as possible.

Note

Conversion is done as per section 3.9 of Vulkan API specification

Warning

This is extremely slow!

Parameters:

bits – The bits of the channel
type – The type of the value stored in the channel
channel – The description of the channel’s format

Returns:

A float that matches the logical value of the channel

uint32_t float_to_channel_bits(float value, ChannelDType type, const TextureChannelFormatDesc &channel)

Converts a float into raw bits of a channel in a certain format that match the provided float as closely as possible.

Note

Conversion is done as per section 3.9 of Vulkan API specification

Note

Bits unused by the channel are set to 0, even for signed formats

Warning

This is extremely slow!

Parameters:

value – The floating point value to convert
type – The type of the value stored in the channel
channel – The description of the channel’s format

Returns:

A uint32_t that contains the bits of the channel

inline TexLoadRes d3d_load_ddsx_tex_contents(BaseTexture *tex, TEXTUREID tid, TEXTUREID paired_tid, const ddsx::Header &hdr, IGenLoad &crd, int q_id, int start_lev = 0, unsigned tex_ld_lev = 0, on_tex_slice_loaded_cb_t on_tex_slice_loaded_cb = nullptr, bool tex_props_inited = false)

bool convert_image_line(const void *input, int width, int in_channels, int in_bits_per_channel, bool in_float, void *output, int out_channels, int out_bits_per_channel, bool out_float, bool swap_rb, bool invert)

Variables

TexLoadRes (*d3d_load_ddsx_tex_contents_impl)(BaseTexture *tex, TEXTUREID tid, TEXTUREID paired_tid, const ddsx::Header &hdr, IGenLoad &crd, int q_id, int start_lev, unsigned tex_ld_lev, on_tex_slice_loaded_cb_t, bool)

TexLoadRes (*d3d_load_ddsx_to_slice)(BaseTexture *tex, int slice, const ddsx::Header &hdr, IGenLoad &crd, int q_id, int start_lev, unsigned tex_ld_lev): load texture content from DDSx stream using DDSx header to specified slice of previously allocated array texture

struct TextureChannelFormatDesc

#include <dag_tex3d.h>

Public Members

int8_t bits

int8_t offset

bool isFloatPoint

bool isSigned

bool isNormalized

struct TextureFormatDesc

#include <dag_tex3d.h>

Public Functions

inline bool hasAlpha() const

inline bool isDepth() const

inline int rgbaChannelsCount() const

inline int channelsCount() const

Public Members

uint32_t dagorTextureFormat

uint16_t bytesPerElement

bool isBlockFormat

uint8_t elementWidth

uint8_t elementHeight

ChannelDType mainChannelsType

ChannelDType stencilChannelType

TextureChannelFormatDesc r

TextureChannelFormatDesc g

TextureChannelFormatDesc b

TextureChannelFormatDesc a

TextureChannelFormatDesc depth

TextureChannelFormatDesc stencil

struct TextureInfo

#include <dag_tex3d.h>

Public Members

uint16_t w = 1: width, height, depth (for VOLTEX)

uint16_t h = 1

uint16_t d = 1

uint16_t a = 1: array slices (slice count for ARRTEX, 6 for CUBETEX, or 6 * <array size> for CUBEARRTEX)

uint16_t mipLevels = 0: all mips

D3DResourceType type = {}: resource type (D3DResourceType::TEX, …)

uint8_t isCommitted = 0

unsigned cflg = 0: texture creation flags

class BaseTexture : public D3dResource

#include <dag_tex3d.h>

Public Functions

inline virtual bool setReloadCallback(IReloadData*)

virtual int generateMips() = 0

virtual int update(BaseTexture *src) = 0

inline int calcSubResIdx(int level, int slice = 0) const

virtual int updateSubRegion(BaseTexture *src, int src_subres_idx, int src_x, int src_y, int src_z, int src_w, int src_h, int src_d, int dest_subres_idx, int dest_x, int dest_y, int dest_z) = 0

inline virtual int updateSubRegionNoOrder(BaseTexture *src, int src_subres_idx, int src_x, int src_y, int src_z, int src_w, int src_h, int src_d, int dest_subres_idx, int dest_x, int dest_y, int dest_z)

virtual int level_count() const = 0

virtual int texmiplevel(int minlevel, int maxlevel) = 0

inline virtual bool isCubeArray() const

inline virtual void setReadStencil(bool)

inline virtual void setTID(TEXTUREID)

inline virtual TEXTUREID getTID() const

inline const char *getTexName() const

virtual int lockimg(void**, int &stride_bytes, int level, unsigned flags) = 0

virtual int lockimg(void**, int &stride_bytes, int layer, int level, unsigned flags) = 0

inline virtual int unlockimg()

inline int unlock()

inline virtual int lockbox(void**, int&, int&, int, unsigned)

inline virtual int unlockbox()

virtual int getinfo(TextureInfo &info, int level = 0) const = 0

template<typename T>
inline int lockimgEx(T **p, int &stride_bytes, int level = 0, unsigned flags = TEXLOCK_DEFAULT)

inline virtual bool updateTexResFormat(unsigned): changes texture format (if possible and supported by driver) to specified ‘d3d_format’ (ddsx::Header::d3dFormat)

inline virtual BaseTexture *makeTmpTexResCopy(int, int, int, int): created temporary BaseTexture with texture res object with given dimensions (texture subtype and format are used from original)

inline virtual void replaceTexResObject(BaseTexture *&new_tex): replaces texture res object with new one of new_tex and then destroys new_tex (destruction may be delayed by driver)

inline virtual bool allocateTex(): forces allocation of texture resource; return true if tex allocated and ready for use

inline virtual void discardTex(): discards texture and returns it to STUB state

inline virtual BaseTexture *downSize(int width, int height, int depth, int mips, unsigned start_src_level, unsigned level_offset)

inline virtual BaseTexture *upSize(int width, int height, int depth, int mips, unsigned start_src_level, unsigned level_offset)

BaseTexture() = default

BaseTexture(BaseTexture&&) = default

BaseTexture &operator=(BaseTexture&&) = default

Public Static Functions

static inline int calcSubResIdx(int level, int slice, int mip_levels)

Protected Functions

~BaseTexture() = default

Protected Static Attributes

static constexpr int TEX_COPIED = 1 << 30

struct IReloadData

#include <dag_tex3d.h>

Public Functions

inline virtual ~IReloadData()

virtual void reloadD3dRes(BaseTexture *t) = 0

virtual void destroySelf() = 0

namespace ddsx

namespace d3d

Functions

bool check_texformat(int cflg)

Check whether the specified texture format is available.

Parameters:: cflg – The texture format to check.
Returns:: Returns false if a texture of the specified format cannot be created, otherwise returns true.

int get_max_sample_count(int cflg)

Get the maximum sample count for the given texture format.

Parameters:: cflg – The texture format.
Returns:: The maximum sample count for the given texture format.

unsigned get_texformat_usage(int cflg, D3DResourceType type = D3DResourceType::TEX)

Get the texture format usage for the given texture format.

Todo:: Use enum class as a returned type.

Parameters:

cflg – The texture format.
type – The resource type (default value is D3DResourceType::TEX).

Returns:

The texture format usage. One of the USAGE_XXX flags.

bool issame_texformat(int cflg1, int cflg2)

Check whether two texture creation flags result in the same format.

Parameters:

cflg1 – The first texture creation flag.
cflg2 – The second texture creation flag.

Returns:

Returns true if the two texture creation flags result in the same format, otherwise returns false.

bool check_cubetexformat(int cflg)

Check whether the specified cube texture format is available.

Parameters:: cflg – The cube texture format to check.
Returns:: Returns false if a cube texture of the specified format cannot be created, otherwise returns true.

bool check_voltexformat(int cflg)

Check whether the specified volume texture format is available.

Parameters:: cflg – The volume texture format to check.
Returns:: Returns false if a volume texture of the specified format cannot be created, otherwise returns true.

BaseTexture *create_tex(TexImage32 *img, int w, int h, int flg, int levels, const char *stat_name = nullptr)

Create a texture.

Parameters:

img – 32-bit image data. nullptr if there are no image data.
w – The width of the texture.
h – The height of the texture.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created texture, or nullptr on error.

BaseTexture *create_ddsx_tex(IGenLoad &crd, int flg, int quality_id, int levels = 0, const char *stat_name = nullptr)

Create a texture from a DDSx stream.

Parameters:

crd – The DDSx stream.
flg – The texture creation flags.
quality_id – The quality index.
levels – The number of loaded mipmaps (0=all, >0=only first ‘levels’ mipmaps).
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created texture, or nullptr on error.

BaseTexture *alloc_ddsx_tex(const ddsx::Header &hdr, int flg, int quality_id, int levels = 0, const char *stat_name = nullptr, int stub_tex_idx = -1)

Allocate a texture object using a DDSx header (not texture contents loaded at this time).

Parameters:

hdr – The DDSx header.
flg – The texture creation flags.
quality_id – The quality index.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).
stub_tex_idx – The index of the stub texture (default value is -1).

Returns:

A pointer to the allocated texture, or nullptr on error.

inline TexLoadRes load_ddsx_tex_contents(BaseTexture *t, const ddsx::Header &hdr, IGenLoad &crd, int q_id)

Load the texture content from a DDSx stream using a DDSx header for a previously allocated texture.

Parameters:

t – The previously allocated texture.
hdr – The DDSx header.
crd – The DDSx stream.
q_id – The quality index.

Returns:

Returns true if the texture content was successfully loaded, otherwise returns false.

BaseTexture *create_cubetex(int size, int flg, int levels, const char *stat_name = nullptr)

Create a cubic texture.

Parameters:

size – The size of the texture. (6 faces size x size)
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created texture, or nullptr on error.

BaseTexture *create_voltex(int w, int h, int d, int flg, int levels, const char *stat_name = nullptr)

Create a volume texture.

Parameters:

w – The width of the texture.
h – The height of the texture.
d – The depth of the texture.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created texture, or nullptr on error.

BaseTexture *create_array_tex(int w, int h, int d, int flg, int levels, const char *stat_name)

Create a texture2d array.

Parameters:

w – The width of the texture.
h – The height of the texture.
d – Amount of textures in the array.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes.

Returns:

A pointer to the created texture, or nullptr on error.

BaseTexture *create_cube_array_tex(int side, int d, int flg, int levels, const char *stat_name)

Create a cube array tex object.

Parameters:

side – The size of the texture. (6 faces size x size)
d – Amount of textures in the array.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes.

Returns:

A pointer to the created texture, or nullptr on error.

BaseTexture *alias_tex(BaseTexture *baseTexture, TexImage32 *img, int w, int h, int flg, int levels, const char *stat_name = nullptr)

Create a texture alias, a texture using the same memory as another texture but with different properties. The alias may use a different resolution, format or mip level, subject to restrictions below.

Deprecated:: Always prefer higher-level APIs for saving memory (e.g. frame graph, ResizableTex). Avoid using this as much as possible, it will be removed in favor of using heaps via a frame graph system.

Warning

You also must dispatch a RB_ALIAS_FROM/RB_ALIAS_TO barrier after you stop using one of the aliases and before you start using a different alias, where all textures occupying the same memory are considered to be aliases of each other.

Warning

After switching to a new alias, it will contain garbage and will need to be initialized. This API does NOT guarantee data inheritance whatsoever. It is to be used for memory reuse only.

Warning

It is not guaranteed that an intuitively smaller alias can be created from a bigger texture. Decreasing the resolution by several pixels causes the amount of memory needed to store the texture to INCREASE on some platforms for some formats and some concrete resolutions. Hence, this function CAN fail and will return nullptr and logerr in such a case. Use d3d::get_resource_allocation_properties to check whether the alias will not take up more memory than the original texture before calling this API.

Parameters:

baseTexture – The base texture to alias.
img – 32-bit image data.
w – The width of the texture.
h – The height of the texture.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created texture alias, or nullptr on error.

BaseTexture *alias_cubetex(BaseTexture *baseTexture, int size, int flg, int levels, const char *stat_name = nullptr)

Create a cube texture alias, a texture using the same memory as another cube texture but with a different format.

Parameters:

baseTexture – The base cube texture to alias.
size – The size of the texture.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created cube texture alias, or nullptr on error.

BaseTexture *alias_voltex(BaseTexture *baseTexture, int w, int h, int d, int flg, int levels, const char *stat_name = nullptr)

Create a volume texture alias, a texture using the same memory as another volume texture but with a different format.

Parameters:

baseTexture – The base volume texture to alias.
w – The width of the texture.
h – The height of the texture.
d – The depth of the texture.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created volume texture alias, or nullptr on error.

BaseTexture *alias_array_tex(BaseTexture *baseTexture, int w, int h, int d, int flg, int levels, const char *stat_name)

Create a texture2d array alias, a texture using the same memory as another texture2d array but with a different format.

Parameters:

baseTexture – The base texture2d array to alias.
w – The width of the texture.
h – The height of the texture.
d – Amount of textures in the array.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created texture2d array alias, or nullptr on error.

BaseTexture *alias_cube_array_tex(BaseTexture *baseTexture, int side, int d, int flg, int levels, const char *stat_name)

Create a cube array texture alias, a texture using the same memory as another cube array texture but with a different format.

Parameters:

baseTexture – The base cube array texture to alias.
side – The side of the cube texture.
d – Amount of textures in the array.
flg – The texture creation flags.
levels – The maximum number of mipmap levels.
stat_name – The name of the texture for statistics purposes (optional).

Returns:

A pointer to the created cube array texture alias, or nullptr on error.

bool stretch_rect(BaseTexture *src, BaseTexture *dst, const RectInt *rsrc = nullptr, const RectInt *rdst = nullptr)

Stretch a rectangle from the source texture to the destination texture.

Under the hood it is a call of CopySubresourceRegion if source and destination textures are the same type and their texel could be mapped one to one. Otherwise it is an execution of a shader that does the stretching.

Parameters:

src – The source texture.
dst – The destination texture.
rsrc – The source rectangle (optional).
rdst – The destination rectangle (optional).

Returns:

Returns true if the stretch operation was successful, otherwise returns false.

void get_texture_statistics(uint32_t *num_textures, uint64_t *total_mem, String *out_dump)

Get the texture statistics.

Parameters:

num_textures – Pointer to store the number of textures.
total_mem – Pointer to store the total memory used by textures.
out_dump – Pointer to store the texture statistics dump.

bool set_tex(unsigned shader_stage, unsigned slot, BaseTexture *tex)

Set a texture for a shader stage and slot.

Parameters:

shader_stage – The shader stage. One of the STAGE_XXX flags.
slot – The slot.
tex – The texture to set.

Returns:

Returns true if the texture was successfully set, otherwise returns false.

inline bool settex(int slot, BaseTexture *tex)

Set a texture for a pixel shader slot.

Parameters:

slot – The slot.
tex – The texture to set.

Returns:

Returns true if the texture was successfully set, otherwise returns false.

inline bool settex_vs(int slot, BaseTexture *tex)

Set a texture for a vertex shader slot.

Parameters:

slot – The slot.
tex – The texture to set.

Returns:

Returns true if the texture was successfully set, otherwise returns false.

bool discard_tex(BaseTexture *tex)

Discard the texture. It initializes the texture leaving the texels in an undefined state.

Parameters:: tex – Texture to discard. Now usage is limited to UA and RT textures only.
Returns:: true if the operation was successful, false otherwise.