GPU_texture.hh

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2005 Blender Authors
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once
 
#include <string>
 
#include "BLI_assert.h"
#include "BLI_utildefines.h"
 
#include "GPU_state.hh"
 
namespace blender::gpu {
class VertBuf;
}
 
/* -------------------------------------------------------------------- */
enum GPUSamplerFiltering {
  GPU_SAMPLER_FILTERING_DEFAULT = 0,
  GPU_SAMPLER_FILTERING_LINEAR = (1 << 0),
  GPU_SAMPLER_FILTERING_MIPMAP = (1 << 1),
  GPU_SAMPLER_FILTERING_ANISOTROPIC = (1 << 2),
};
 
ENUM_OPERATORS(GPUSamplerFiltering, GPU_SAMPLER_FILTERING_ANISOTROPIC)
 
 
static const int GPU_SAMPLER_FILTERING_TYPES_COUNT = (GPU_SAMPLER_FILTERING_LINEAR |
                                                      GPU_SAMPLER_FILTERING_MIPMAP |
                                                      GPU_SAMPLER_FILTERING_ANISOTROPIC) +
                                                     1;
 
enum GPUSamplerExtendMode {
  GPU_SAMPLER_EXTEND_MODE_EXTEND = 0,
  GPU_SAMPLER_EXTEND_MODE_REPEAT,
  GPU_SAMPLER_EXTEND_MODE_MIRRORED_REPEAT,
  GPU_SAMPLER_EXTEND_MODE_CLAMP_TO_BORDER,
};
 
#define GPU_SAMPLER_EXTEND_MODES_COUNT (GPU_SAMPLER_EXTEND_MODE_CLAMP_TO_BORDER + 1)
 
enum GPUSamplerCustomType {
  GPU_SAMPLER_CUSTOM_COMPARE = 0,
  GPU_SAMPLER_CUSTOM_ICON,
};
 
#define GPU_SAMPLER_CUSTOM_TYPES_COUNT (GPU_SAMPLER_CUSTOM_ICON + 1)
 
enum GPUSamplerStateType {
  GPU_SAMPLER_STATE_TYPE_PARAMETERS = 0,
  GPU_SAMPLER_STATE_TYPE_CUSTOM,
  GPU_SAMPLER_STATE_TYPE_INTERNAL,
};
 
struct GPUSamplerState {
  GPUSamplerFiltering filtering : 8;
  GPUSamplerExtendMode extend_x : 4;
  GPUSamplerExtendMode extend_yz : 4;
  GPUSamplerCustomType custom_type : 8;
  GPUSamplerStateType type : 8;
 
  static constexpr GPUSamplerState default_sampler()
  {
    return {GPU_SAMPLER_FILTERING_DEFAULT,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_CUSTOM_COMPARE,
            GPU_SAMPLER_STATE_TYPE_PARAMETERS};
  }
 
  static constexpr GPUSamplerState internal_sampler()
  {
    return {GPU_SAMPLER_FILTERING_DEFAULT,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_CUSTOM_COMPARE,
            GPU_SAMPLER_STATE_TYPE_INTERNAL};
  }
 
  static constexpr GPUSamplerState icon_sampler()
  {
    return {GPU_SAMPLER_FILTERING_DEFAULT,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_CUSTOM_ICON,
            GPU_SAMPLER_STATE_TYPE_CUSTOM};
  }
 
  static constexpr GPUSamplerState compare_sampler()
  {
    return {GPU_SAMPLER_FILTERING_DEFAULT,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_EXTEND_MODE_EXTEND,
            GPU_SAMPLER_CUSTOM_COMPARE,
            GPU_SAMPLER_STATE_TYPE_CUSTOM};
  }
 
  void enable_filtering_flag(GPUSamplerFiltering filtering_flags)
  {
    this->filtering = this->filtering | filtering_flags;
  }
 
  void disable_filtering_flag(GPUSamplerFiltering filtering_flags)
  {
    this->filtering = this->filtering & ~filtering_flags;
  }
 
  void set_filtering_flag_from_test(GPUSamplerFiltering filtering_flags, bool test)
  {
    if (test) {
      this->enable_filtering_flag(filtering_flags);
    }
    else {
      this->disable_filtering_flag(filtering_flags);
    }
  }
 
  std::string to_string() const
  {
    if (this->type == GPU_SAMPLER_STATE_TYPE_INTERNAL) {
      return "internal";
    }
 
    if (this->type == GPU_SAMPLER_STATE_TYPE_CUSTOM) {
      switch (this->custom_type) {
        case GPU_SAMPLER_CUSTOM_COMPARE:
          return "compare";
          break;
        case GPU_SAMPLER_CUSTOM_ICON:
          return "icon";
          break;
        default:
          BLI_assert_unreachable();
          return "";
      }
    }
 
    /* The sampler state is of type PARAMETERS, so serialize the parameters. */
    BLI_assert(this->type == GPU_SAMPLER_STATE_TYPE_PARAMETERS);
    std::string serialized_parameters;
 
    if (this->filtering & GPU_SAMPLER_FILTERING_LINEAR) {
      serialized_parameters += "linear-filter_";
    }
 
    if (this->filtering & GPU_SAMPLER_FILTERING_MIPMAP) {
      serialized_parameters += "mipmap_";
    }
 
    if (this->filtering & GPU_SAMPLER_FILTERING_ANISOTROPIC) {
      serialized_parameters += "anisotropic_";
    }
 
    switch (this->extend_x) {
      case GPU_SAMPLER_EXTEND_MODE_EXTEND:
        serialized_parameters += "extend-x_";
        break;
      case GPU_SAMPLER_EXTEND_MODE_REPEAT:
        serialized_parameters += "repeat-x_";
        break;
      case GPU_SAMPLER_EXTEND_MODE_MIRRORED_REPEAT:
        serialized_parameters += "mirrored-repeat-x_";
        break;
      case GPU_SAMPLER_EXTEND_MODE_CLAMP_TO_BORDER:
        serialized_parameters += "clamp-to-border-x_";
        break;
      default:
        BLI_assert_unreachable();
    }
 
    switch (this->extend_yz) {
      case GPU_SAMPLER_EXTEND_MODE_EXTEND:
        serialized_parameters += "extend-y_";
        break;
      case GPU_SAMPLER_EXTEND_MODE_REPEAT:
        serialized_parameters += "repeat-y_";
        break;
      case GPU_SAMPLER_EXTEND_MODE_MIRRORED_REPEAT:
        serialized_parameters += "mirrored-repeat-y_";
        break;
      case GPU_SAMPLER_EXTEND_MODE_CLAMP_TO_BORDER:
        serialized_parameters += "clamp-to-border-y_";
        break;
      default:
        BLI_assert_unreachable();
    }
 
    switch (this->extend_yz) {
      case GPU_SAMPLER_EXTEND_MODE_EXTEND:
        serialized_parameters += "extend-z";
        break;
      case GPU_SAMPLER_EXTEND_MODE_REPEAT:
        serialized_parameters += "repeat-z";
        break;
      case GPU_SAMPLER_EXTEND_MODE_MIRRORED_REPEAT:
        serialized_parameters += "mirrored-repeat-z";
        break;
      case GPU_SAMPLER_EXTEND_MODE_CLAMP_TO_BORDER:
        serialized_parameters += "clamp-to-border-z";
        break;
      default:
        BLI_assert_unreachable();
    }
 
    return serialized_parameters;
  }
 
  bool operator==(GPUSamplerState const &rhs) const
  {
    return this->filtering == rhs.filtering && this->extend_x == rhs.extend_x &&
           this->extend_yz == rhs.extend_yz && this->custom_type == rhs.custom_type &&
           this->type == rhs.type;
  }
};
 
/* -------------------------------------------------------------------- */
enum eGPUTextureFormat {
  /* Formats texture & render-buffer. */
 
  GPU_RGBA8UI,
  GPU_RGBA8I,
  GPU_RGBA8,
  GPU_RGBA16UI,
  GPU_RGBA16I,
  GPU_RGBA16F,
  GPU_RGBA16,
  GPU_RGBA32UI,
  GPU_RGBA32I,
  GPU_RGBA32F,
 
  GPU_RG8UI,
  GPU_RG8I,
  GPU_RG8,
  GPU_RG16UI,
  GPU_RG16I,
  GPU_RG16F,
  GPU_RG16,
  GPU_RG32UI,
  GPU_RG32I,
  GPU_RG32F,
 
  GPU_R8UI,
  GPU_R8I,
  GPU_R8,
  GPU_R16UI,
  GPU_R16I,
  GPU_R16F,
  GPU_R16,
  GPU_R32UI,
  GPU_R32I,
  GPU_R32F,
 
  /* Special formats texture & render-buffer. */
 
  GPU_RGB10_A2,
  GPU_RGB10_A2UI,
  GPU_R11F_G11F_B10F,
  GPU_DEPTH32F_STENCIL8,
  GPU_DEPTH24_STENCIL8,
  GPU_SRGB8_A8,
 
  /* Texture only formats. */
 
  GPU_RGBA8_SNORM,
  GPU_RGBA16_SNORM,
 
  GPU_RGB8UI,
  GPU_RGB8I,
  GPU_RGB8,
  GPU_RGB8_SNORM,
  GPU_RGB16UI,
  GPU_RGB16I,
  GPU_RGB16F,
  GPU_RGB16,
  GPU_RGB16_SNORM,
  GPU_RGB32UI,
  GPU_RGB32I,
  GPU_RGB32F,
 
  GPU_RG8_SNORM,
  GPU_RG16_SNORM,
 
  GPU_R8_SNORM,
  GPU_R16_SNORM,
 
  /* Special formats, texture only. */
  GPU_SRGB8_A8_DXT1, /* BC1 */
  GPU_SRGB8_A8_DXT3, /* BC2 */
  GPU_SRGB8_A8_DXT5, /* BC3 */
  GPU_RGBA8_DXT1,    /* BC1 */
  GPU_RGBA8_DXT3,    /* BC2 */
  GPU_RGBA8_DXT5,    /* BC3 */
  GPU_SRGB8,
  GPU_RGB9_E5,
#if 0 /* TODO: Add support for them. */
  GPU_COMPRESSED_RG_RGTC2,
  GPU_COMPRESSED_SIGNED_RG_RGTC2,
  GPU_COMPRESSED_RED_RGTC1,
  GPU_COMPRESSED_SIGNED_RED_RGTC1,
#endif
 
  /* Depth Formats. */
  GPU_DEPTH_COMPONENT32F,
  GPU_DEPTH_COMPONENT24,
  GPU_DEPTH_COMPONENT16,
};
 
enum eGPUDataFormat {
  GPU_DATA_FLOAT,
  GPU_DATA_HALF_FLOAT,
  GPU_DATA_INT,
  GPU_DATA_UINT,
  GPU_DATA_UBYTE,
  GPU_DATA_UINT_24_8,
  GPU_DATA_10_11_11_REV,
  GPU_DATA_2_10_10_10_REV,
};
 
enum eGPUTextureUsage {
  /* Whether texture is sampled or read during a shader. */
  GPU_TEXTURE_USAGE_SHADER_READ = (1 << 0),
  /* Whether the texture is written to by a shader using imageStore. */
  GPU_TEXTURE_USAGE_SHADER_WRITE = (1 << 1),
  /* Whether a texture is used as an attachment in a frame-buffer. */
  GPU_TEXTURE_USAGE_ATTACHMENT = (1 << 2),
  /* Whether a texture is used to create a texture view utilizing a different texture format to the
   * source textures format. This includes the use of stencil views. */
  GPU_TEXTURE_USAGE_FORMAT_VIEW = (1 << 3),
  /* Whether the texture needs to be read from by the CPU. */
  GPU_TEXTURE_USAGE_HOST_READ = (1 << 4),
  /* When used, the texture will not have any backing storage and can solely exist as a virtual
   * frame-buffer attachment. */
  GPU_TEXTURE_USAGE_MEMORYLESS = (1 << 5),
  /* Whether a texture can support atomic operations. */
  GPU_TEXTURE_USAGE_ATOMIC = (1 << 6),
  /* Create a texture whose usage cannot be defined prematurely.
   * This is unoptimized and should not be used. */
  GPU_TEXTURE_USAGE_GENERAL = (0xFF &
                               (~(GPU_TEXTURE_USAGE_MEMORYLESS | GPU_TEXTURE_USAGE_ATOMIC))),
};
 
ENUM_OPERATORS(eGPUTextureUsage, GPU_TEXTURE_USAGE_GENERAL);
 
/* -------------------------------------------------------------------- */
struct GPUTexture;
 
GPUTexture *GPU_texture_create_1d(const char *name,
                                  int width,
                                  int mip_len,
                                  eGPUTextureFormat format,
                                  eGPUTextureUsage usage,
                                  const float *data);
GPUTexture *GPU_texture_create_1d_array(const char *name,
                                        int width,
                                        int layer_len,
                                        int mip_len,
                                        eGPUTextureFormat format,
                                        eGPUTextureUsage usage,
                                        const float *data);
GPUTexture *GPU_texture_create_2d(const char *name,
                                  int width,
                                  int height,
                                  int mip_len,
                                  eGPUTextureFormat format,
                                  eGPUTextureUsage usage,
                                  const float *data);
GPUTexture *GPU_texture_create_2d_array(const char *name,
                                        int width,
                                        int height,
                                        int layer_len,
                                        int mip_len,
                                        eGPUTextureFormat format,
                                        eGPUTextureUsage usage,
                                        const float *data);
GPUTexture *GPU_texture_create_3d(const char *name,
                                  int width,
                                  int height,
                                  int depth,
                                  int mip_len,
                                  eGPUTextureFormat format,
                                  eGPUTextureUsage usage,
                                  const void *data);
GPUTexture *GPU_texture_create_cube(const char *name,
                                    int width,
                                    int mip_len,
                                    eGPUTextureFormat format,
                                    eGPUTextureUsage usage,
                                    const float *data);
GPUTexture *GPU_texture_create_cube_array(const char *name,
                                          int width,
                                          int layer_len,
                                          int mip_len,
                                          eGPUTextureFormat format,
                                          eGPUTextureUsage usage,
                                          const float *data);
GPUTexture *GPU_texture_create_compressed_2d(const char *name,
                                             int width,
                                             int height,
                                             int mip_len,
                                             eGPUTextureFormat format,
                                             eGPUTextureUsage usage,
                                             const void *data);
 
GPUTexture *GPU_texture_create_from_vertbuf(const char *name, blender::gpu::VertBuf *vertex_buf);
 
GPUTexture *GPU_texture_create_error(int dimension, bool array);
 
/* -------------------------------------------------------------------- */
void GPU_texture_ref(GPUTexture *texture);
 
void GPU_texture_free(GPUTexture *texture);
 
#define GPU_TEXTURE_FREE_SAFE(texture) \
  do { \
    if (texture != nullptr) { \
      GPU_texture_free(texture); \
      texture = nullptr; \
    } \
  } while (0)
 
/* -------------------------------------------------------------------- */
GPUTexture *GPU_texture_create_view(const char *name,
                                    GPUTexture *source_texture,
                                    eGPUTextureFormat view_format,
                                    int mip_start,
                                    int mip_len,
                                    int layer_start,
                                    int layer_len,
                                    bool cube_as_array,
                                    bool use_stencil);
 
/* -------------------------------------------------------------------- */
void GPU_unpack_row_length_set(uint len);
 
void GPU_texture_update(GPUTexture *texture, eGPUDataFormat data_format, const void *data);
 
void GPU_texture_update_sub(GPUTexture *texture,
                            eGPUDataFormat data_format,
                            const void *pixels,
                            int offset_x,
                            int offset_y,
                            int offset_z,
                            int width,
                            int height,
                            int depth);
 
void GPU_texture_update_mipmap(GPUTexture *texture,
                               int mip_level,
                               eGPUDataFormat data_format,
                               const void *pixels);
 
void GPU_texture_clear(GPUTexture *texture, eGPUDataFormat data_format, const void *data);
 
void GPU_texture_copy(GPUTexture *dst, GPUTexture *src);
 
void GPU_texture_update_mipmap_chain(GPUTexture *texture);
 
void *GPU_texture_read(GPUTexture *texture, eGPUDataFormat data_format, int mip_level);
 
/* -------------------------------------------------------------------- */
void GPU_texture_bind(GPUTexture *texture, int unit);
void GPU_texture_bind_ex(GPUTexture *texture, GPUSamplerState state, int unit);
void GPU_texture_unbind(GPUTexture *texture);
void GPU_texture_unbind_all();
 
void GPU_texture_image_bind(GPUTexture *texture, int unit);
void GPU_texture_image_unbind(GPUTexture *texture);
void GPU_texture_image_unbind_all();
 
/* -------------------------------------------------------------------- */
void GPU_texture_compare_mode(GPUTexture *texture, bool use_compare);
 
void GPU_texture_filter_mode(GPUTexture *texture, bool use_filter);
 
void GPU_texture_mipmap_mode(GPUTexture *texture, bool use_mipmap, bool use_filter);
 
void GPU_texture_anisotropic_filter(GPUTexture *texture, bool use_aniso);
 
void GPU_texture_extend_mode_x(GPUTexture *texture, GPUSamplerExtendMode extend_mode);
 
void GPU_texture_extend_mode_y(GPUTexture *texture, GPUSamplerExtendMode extend_mode);
 
void GPU_texture_extend_mode(GPUTexture *texture, GPUSamplerExtendMode extend_mode);
 
void GPU_texture_swizzle_set(GPUTexture *texture, const char swizzle[4]);
 
/* -------------------------------------------------------------------- */
int GPU_texture_dimensions(const GPUTexture *texture);
 
int GPU_texture_width(const GPUTexture *texture);
 
int GPU_texture_height(const GPUTexture *texture);
 
int GPU_texture_depth(const GPUTexture *texture);
 
int GPU_texture_layer_count(const GPUTexture *texture);
 
int GPU_texture_mip_count(const GPUTexture *texture);
 
eGPUTextureFormat GPU_texture_format(const GPUTexture *texture);
 
eGPUTextureUsage GPU_texture_usage(const GPUTexture *texture);
 
bool GPU_texture_is_array(const GPUTexture *texture);
 
bool GPU_texture_is_cube(const GPUTexture *texture);
 
bool GPU_texture_has_depth_format(const GPUTexture *texture);
 
bool GPU_texture_has_stencil_format(const GPUTexture *texture);
 
bool GPU_texture_has_integer_format(const GPUTexture *texture);
 
bool GPU_texture_has_float_format(const GPUTexture *tex);
 
bool GPU_texture_has_normalized_format(const GPUTexture *tex);
 
bool GPU_texture_has_signed_format(const GPUTexture *tex);
 
void GPU_texture_get_mipmap_size(GPUTexture *texture, int mip_level, int *r_size);
 
/* -------------------------------------------------------------------- */
int GPU_texture_original_width(const GPUTexture *texture);
int GPU_texture_original_height(const GPUTexture *texture);
void GPU_texture_original_size_set(GPUTexture *texture, int width, int height);
 
#ifndef GPU_NO_USE_PY_REFERENCES
void **GPU_texture_py_reference_get(GPUTexture *texture);
void GPU_texture_py_reference_set(GPUTexture *texture, void **py_ref);
#endif
 
int GPU_texture_opengl_bindcode(const GPUTexture *texture);
 
/* -------------------------------------------------------------------- */
size_t GPU_texture_component_len(eGPUTextureFormat format);
 
size_t GPU_texture_dataformat_size(eGPUDataFormat data_format);
 
const char *GPU_texture_format_name(eGPUTextureFormat format);
 
unsigned int GPU_texture_memory_usage_get();
 
void GPU_samplers_update();
 
/* -------------------------------------------------------------------- */
struct GPUPixelBuffer;
 
GPUPixelBuffer *GPU_pixel_buffer_create(size_t byte_size);
 
void GPU_pixel_buffer_free(GPUPixelBuffer *pixel_buf);
 
void *GPU_pixel_buffer_map(GPUPixelBuffer *pixel_buf);
 
void GPU_pixel_buffer_unmap(GPUPixelBuffer *pixel_buf);
 
size_t GPU_pixel_buffer_size(GPUPixelBuffer *pixel_buf);
 
int64_t GPU_pixel_buffer_get_native_handle(GPUPixelBuffer *pixel_buf);
 
void GPU_texture_update_sub_from_pixel_buffer(GPUTexture *texture,
                                              eGPUDataFormat data_format,
                                              GPUPixelBuffer *pixel_buf,
                                              int offset_x,
                                              int offset_y,
                                              int offset_z,
                                              int width,
                                              int height,
                                              int depth);