CUDA Driver API :: CUDA Toolkit Documentation

6.28. 纹理对象管理

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

Functions

CUresult cuTexObjectCreate ( CUtexObject* pTexObject, const CUDA_RESOURCE_DESC* pResDesc, const CUDA_TEXTURE_DESC* pTexDesc, const CUDA_RESOURCE_VIEW_DESC* pResViewDesc ): Creates a texture object.
CUresult cuTexObjectDestroy ( CUtexObject texObject ): Destroys a texture object.
CUresult cuTexObjectGetResourceDesc ( CUDA_RESOURCE_DESC* pResDesc, CUtexObject texObject ): Returns a texture object's resource descriptor.
CUresult cuTexObjectGetResourceViewDesc ( CUDA_RESOURCE_VIEW_DESC* pResViewDesc, CUtexObject texObject ): Returns a texture object's resource view descriptor.
CUresult cuTexObjectGetTextureDesc ( CUDA_TEXTURE_DESC* pTexDesc, CUtexObject texObject ): Returns a texture object's texture descriptor.

Functions

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

创建一个纹理对象。

参数

pTexObject: - Texture object to create
pResDesc: - Resource descriptor
pTexDesc: - Texture descriptor
pResViewDesc: - Resource view descriptor

CUDA_SUCCESS, CUDA_ERROR_DEINITIALIZED, CUDA_ERROR_NOT_INITIALIZED, CUDA_ERROR_INVALID_CONTEXT, CUDA_ERROR_INVALID_VALUE

描述

创建一个纹理对象并在pTexObject中返回它。pResDesc描述了要从中获取纹理的数据。pTexDesc描述了应如何采样数据。pResViewDesc是一个可选参数，它指定了pResDesc所描述数据的替代格式，并描述了在纹理处理时要限制访问的子资源区域。只有当资源类型是CUDA数组或非块压缩格式的CUDA mipmapped数组时，才能指定pResViewDesc。

纹理对象仅支持计算能力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;

where:

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。

flags必须设置为零。

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;

where

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 can be any combination of the following:
- 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数组或使用CUDA_ARRAY3D_CUBEMAP标志创建的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;

where:

CUDA_RESOURCE_VIEW_DESC::format 指定应如何解释CUDA数组或CUDA多级渐远纹理数组中包含的数据。请注意，这可能会导致纹理数据大小发生变化。如果资源视图格式是块压缩格式，则底层CUDA数组或CUDA多级渐远纹理数组必须具有CU_AD_FORMAT_UNSIGNED_INT32基本格式，并根据块压缩格式包含2或4个通道。例如，BC1和BC4要求底层CUDA数组具有2通道的CU_AD_FORMAT_UNSIGNED_INT32格式。其他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零级。对于非mipmap资源，此值必须为零。CUDA_TEXTURE_DESC::minMipmapLevelClamp 和 CUDA_TEXTURE_DESC::maxMipmapLevelClamp 将相对于此值进行计算。例如，如果firstMipmapLevel设为2，且minMipmapLevelClamp指定为1.2，则实际的最小mipmap层级限制将为3.2。