CUDA 驱动程序 API :: CUDA Toolkit 文档

6.28. 纹理对象管理

本节介绍低级别 CUDA 驱动程序应用程序编程接口的纹理对象管理功能。纹理对象 API 仅在计算能力为 3.0 或更高的设备上受支持。

函数

CUresult cuTexObjectCreate ( CUtexObject* pTexObject, const CUDA_RESOURCE_DESC* pResDesc, const CUDA_TEXTURE_DESC* pTexDesc, const CUDA_RESOURCE_VIEW_DESC* pResViewDesc ): 创建纹理对象。
CUresult cuTexObjectDestroy ( CUtexObject texObject ): 销毁纹理对象。
CUresult cuTexObjectGetResourceDesc ( CUDA_RESOURCE_DESC* pResDesc, CUtexObject texObject ): 返回纹理对象的资源描述符。
CUresult cuTexObjectGetResourceViewDesc ( CUDA_RESOURCE_VIEW_DESC* pResViewDesc, CUtexObject texObject ): 返回纹理对象的资源视图描述符。
CUresult cuTexObjectGetTextureDesc ( CUDA_TEXTURE_DESC* pTexDesc, CUtexObject texObject ): 返回纹理对象的纹理描述符。

函数

CUresult cuTexObjectCreate ( CUtexObject* pTexObject, const CUDA_RESOURCE_DESC* pResDesc, const CUDA_TEXTURE_DESC* pTexDesc, const CUDA_RESOURCE_VIEW_DESC* pResViewDesc )

创建纹理对象。

参数

pTexObject: - 要创建的纹理对象
pResDesc: - 资源描述符
pTexDesc: - 纹理描述符
pResViewDesc: - 资源视图描述符

返回值

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE

描述

创建纹理对象并在pTexObject. pResDesc中返回它，描述了要从中进行纹理化的数据。pTexDesc描述了应如何采样数据。pResViewDesc是一个可选参数，用于指定由pResDesc描述的数据的备用格式，并描述在进行纹理化时要限制访问的子资源区域。pResViewDesc只有当资源类型为 CUDA 数组或 CUDA mipmapped 数组且不是块压缩格式时才能指定。

纹理对象仅在计算能力为 3.0 或更高的设备上受支持。此外，纹理对象是不透明值，因此，应仅通过 CUDA API 调用访问。

CUDA_RESOURCE_DESC 结构定义为

‎        typedef struct CUDA_RESOURCE_DESC_st
              {
                  CUresourcetype resType;
      
                  union {
                      struct {
                          CUarray hArray;
                      } array;
                      struct {
                          CUmipmappedArray hMipmappedArray;
                      } mipmap;
                      struct {
                          CUdeviceptr devPtr;
                          CUarray_format format;
                          unsigned int numChannels;
                          size_t sizeInBytes;
                      } linear;
                      struct {
                          CUdeviceptr devPtr;
                          CUarray_format format;
                          unsigned int numChannels;
                          size_t width;
                          size_t height;
                          size_t pitchInBytes;
                      } pitch2D;
                  } res;
      
                  unsigned int flags;
              } CUDA_RESOURCE_DESC;

其中

CUDA_RESOURCE_DESC::resType 指定要从中进行纹理化的资源类型。CUresourceType 定义为

‎        typedef enum CUresourcetype_enum {
                  CU_RESOURCE_TYPE_ARRAY           = 0x00,
                  CU_RESOURCE_TYPE_MIPMAPPED_ARRAY = 0x01,
                  CU_RESOURCE_TYPE_LINEAR          = 0x02,
                  CU_RESOURCE_TYPE_PITCH2D         = 0x03
              } CUresourcetype;

如果 CUDA_RESOURCE_DESC::resType 设置为 CU_RESOURCE_TYPE_ARRAY，则必须将 CUDA_RESOURCE_DESC::res::array::hArray 设置为有效的 CUDA 数组句柄。

如果 CUDA_RESOURCE_DESC::resType 设置为 CU_RESOURCE_TYPE_MIPMAPPED_ARRAY，则必须将 CUDA_RESOURCE_DESC::res::mipmap::hMipmappedArray 设置为有效的 CUDA mipmapped 数组句柄。

如果 CUDA_RESOURCE_DESC::resType 设置为 CU_RESOURCE_TYPE_LINEAR，则必须将 CUDA_RESOURCE_DESC::res::linear::devPtr 设置为有效的设备指针，该指针与 CU_DEVICE_ATTRIBUTE_TEXTURE_ALIGNMENT 对齐。CUDA_RESOURCE_DESC::res::linear::format 和 CUDA_RESOURCE_DESC::res::linear::numChannels 描述了每个组件的格式和每个数组元素的组件数。CUDA_RESOURCE_DESC::res::linear::sizeInBytes 指定了数组的大小（以字节为单位）。线性地址范围中的元素总数不能超过 CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE1D_LINEAR_WIDTH。元素数计算为 (sizeInBytes / (sizeof(format) * numChannels))。

如果 CUDA_RESOURCE_DESC::resType 设置为 CU_RESOURCE_TYPE_PITCH2D，则必须将 CUDA_RESOURCE_DESC::res::pitch2D::devPtr 设置为有效的设备指针，该指针与 CU_DEVICE_ATTRIBUTE_TEXTURE_ALIGNMENT 对齐。CUDA_RESOURCE_DESC::res::pitch2D::format 和 CUDA_RESOURCE_DESC::res::pitch2D::numChannels 描述了每个组件的格式和每个数组元素的组件数。CUDA_RESOURCE_DESC::res::pitch2D::width 和 CUDA_RESOURCE_DESC::res::pitch2D::height 分别指定了数组的宽度和高度（以元素为单位），并且不能超过 CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_WIDTH 和 CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_HEIGHT。CUDA_RESOURCE_DESC::res::pitch2D::pitchInBytes 指定了以字节为单位的两行之间的间距，并且必须与 CU_DEVICE_ATTRIBUTE_TEXTURE_PITCH_ALIGNMENT 对齐。间距不能超过 CU_DEVICE_ATTRIBUTE_MAXIMUM_TEXTURE2D_LINEAR_PITCH。

标志必须设置为零。

CUDA_TEXTURE_DESC 结构定义为

‎        typedef struct CUDA_TEXTURE_DESC_st {
                  CUaddress_mode addressMode[3];
                  CUfilter_mode filterMode;
                  unsigned int flags;
                  unsigned int maxAnisotropy;
                  CUfilter_mode mipmapFilterMode;
                  float mipmapLevelBias;
                  float minMipmapLevelClamp;
                  float maxMipmapLevelClamp;
              } CUDA_TEXTURE_DESC;

其中

CUDA_TEXTURE_DESC::addressMode 指定纹理数据每个维度的寻址模式。CUaddress_mode 定义为

‎        typedef enum CUaddress_mode_enum {
                  CU_TR_ADDRESS_MODE_WRAP = 0,
                  CU_TR_ADDRESS_MODE_CLAMP = 1,
                  CU_TR_ADDRESS_MODE_MIRROR = 2,
                  CU_TR_ADDRESS_MODE_BORDER = 3
              } CUaddress_mode;

如果 CUDA_RESOURCE_DESC::resType 为 CU_RESOURCE_TYPE_LINEAR，则忽略此项。此外，如果未设置标志 CU_TRSF_NORMALIZED_COORDINATES，则唯一支持的寻址模式为 CU_TR_ADDRESS_MODE_CLAMP。

CUDA_TEXTURE_DESC::filterMode 指定从纹理中提取时要使用的滤波模式。CUfilter_mode 定义为

‎        typedef enum CUfilter_mode_enum {
                  CU_TR_FILTER_MODE_POINT = 0,
                  CU_TR_FILTER_MODE_LINEAR = 1
              } CUfilter_mode;

如果 CUDA_RESOURCE_DESC::resType 为 CU_RESOURCE_TYPE_LINEAR，则忽略此项。

CUDA_TEXTURE_DESC::flags 可以是以下各项的任意组合
- CU_TRSF_READ_AS_INTEGER，它抑制了纹理将整数数据提升为 [0, 1] 范围内的浮点数据的默认行为。请注意，无论是否指定此标志，具有 32 位整数格式的纹理都不会被提升。
- CU_TRSF_NORMALIZED_COORDINATES，它抑制了纹理坐标范围为 [0, Dim) 的默认行为，其中 Dim 是 CUDA 数组的宽度或高度。相反，纹理坐标 [0, 1.0) 引用数组维度的整个宽度；请注意，对于 CUDA mipmapped 数组，必须设置此标志。
- CU_TRSF_DISABLE_TRILINEAR_OPTIMIZATION，它禁用任何三线性滤波优化。三线性优化通过在可以紧密近似预期结果的情况下允许对纹理进行双线性滤波来提高纹理滤波性能。
- CU_TRSF_SEAMLESS_CUBEMAP，它启用无缝立方体贴图滤波。只有当底层资源是使用标志 CUDA_ARRAY3D_CUBEMAP 创建的 CUDA 数组或 CUDA mipmapped 数组时，才能指定此标志。启用无缝立方体贴图滤波后，将忽略 CUDA_TEXTURE_DESC::addressMode 指定的纹理寻址模式。相反，如果 CUDA_TEXTURE_DESC::filterMode 设置为 CU_TR_FILTER_MODE_POINT，则寻址模式 CU_TR_ADDRESS_MODE_CLAMP 将应用于所有维度。如果 CUDA_TEXTURE_DESC::filterMode 设置为 CU_TR_FILTER_MODE_LINEAR，则在沿立方体面边界采样时将执行无缝立方体贴图滤波。

CUDA_TEXTURE_DESC::maxAnisotropy 指定在执行各向异性滤波时要使用的最大各向异性比率。此值将被限制在 [1,16] 范围内。

CUDA_TEXTURE_DESC::mipmapFilterMode 指定当计算出的 mipmap 级别位于两个定义的 mipmap 级别之间时的滤波模式。

CUDA_TEXTURE_DESC::mipmapLevelBias 指定要应用于计算出的 mipmap 级别的偏移量。

CUDA_TEXTURE_DESC::minMipmapLevelClamp 指定要限制访问的 mipmap 级别范围的下限。

CUDA_TEXTURE_DESC::maxMipmapLevelClamp 指定要限制访问的 mipmap 级别范围的上限。

CUDA_RESOURCE_VIEW_DESC 结构定义为

‎        typedef struct CUDA_RESOURCE_VIEW_DESC_st
              {
                  CUresourceViewFormat format;
                  size_t width;
                  size_t height;
                  size_t depth;
                  unsigned int firstMipmapLevel;
                  unsigned int lastMipmapLevel;
                  unsigned int firstLayer;
                  unsigned int lastLayer;
              } CUDA_RESOURCE_VIEW_DESC;

其中

CUDA_RESOURCE_VIEW_DESC::format 指定应如何解释 CUDA 数组或 CUDA mipmapped 数组中包含的数据。请注意，这可能会导致纹理数据大小发生变化。如果资源视图格式为块压缩格式，则底层 CUDA 数组或 CUDA mipmapped 数组必须具有 CU_AD_FORMAT_UNSIGNED_INT32 的基本格式。具有 2 个或 4 个通道，具体取决于块压缩格式。例如，BC1 和 BC4 要求底层 CUDA 数组具有 CU_AD_FORMAT_UNSIGNED_INT32 格式和 2 个通道。其他 BC 格式要求底层资源具有相同的基本格式，但具有 4 个通道。

CUDA_RESOURCE_VIEW_DESC::width 指定纹理数据的新宽度。如果资源视图格式为块压缩格式，则此值必须是资源原始宽度的 4 倍。对于非块压缩格式，此值必须等于原始资源的值。

CUDA_RESOURCE_VIEW_DESC::height 指定纹理数据的新高度。如果资源视图格式为块压缩格式，则此值必须是资源原始高度的 4 倍。对于非块压缩格式，此值必须等于原始资源的值。

CUDA_RESOURCE_VIEW_DESC::depth 指定纹理数据的新深度。此值必须等于原始资源的值。

CUDA_RESOURCE_VIEW_DESC::firstMipmapLevel 指定最详细的 mipmap 级别。这将是新的 mipmap 级别零。对于非 mipmapped 资源，此值必须为零。CUDA_TEXTURE_DESC::minMipmapLevelClamp 和 CUDA_TEXTURE_DESC::maxMipmapLevelClamp 将相对于此值。例如，如果 firstMipmapLevel 设置为 2，并且指定了 1.2 的 minMipmapLevelClamp，则实际的最小 mipmap 级别钳位将为 3.2。