CUDA Runtime API :: CUDA Toolkit Documentation

6.27. 纹理对象管理

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

Functions

__host__ cudaChannelFormatDesc cudaCreateChannelDesc ( int x, int y, int z, int w, cudaChannelFormatKind f ): Returns a channel descriptor using the specified format.
__host__ cudaError_t cudaCreateTextureObject ( cudaTextureObject_t* pTexObject, const cudaResourceDesc* pResDesc, const cudaTextureDesc* pTexDesc, const cudaResourceViewDesc* pResViewDesc ): Creates a texture object.
__host__ cudaError_t cudaDestroyTextureObject ( cudaTextureObject_t texObject ): Destroys a texture object.
__host__ cudaError_t cudaGetChannelDesc ( cudaChannelFormatDesc* desc, cudaArray_const_t array ): Get the channel descriptor of an array.
__host__ cudaError_t cudaGetTextureObjectResourceDesc ( cudaResourceDesc* pResDesc, cudaTextureObject_t texObject ): Returns a texture object's resource descriptor.
__host__ cudaError_t cudaGetTextureObjectResourceViewDesc ( cudaResourceViewDesc* pResViewDesc, cudaTextureObject_t texObject ): Returns a texture object's resource view descriptor.
__host__ cudaError_t cudaGetTextureObjectTextureDesc ( cudaTextureDesc* pTexDesc, cudaTextureObject_t texObject ): Returns a texture object's texture descriptor.

Functions

__host__ cudaChannelFormatDesc cudaCreateChannelDesc ( int x, int y, int z, int w, cudaChannelFormatKind f )

返回使用指定格式的通道描述符。

参数

x: - X component
y: - Y component
z: - Z component
w: - W component
f: - Channel format

具有格式f的通道描述符

描述

返回一个通道描述符，其格式为f，各分量x、y、z和w的位数。该cudaChannelFormatDesc定义为：

‎  struct cudaChannelFormatDesc {
          int x, y, z, w;
          enum cudaChannelFormatKind 
                  f;
        };

其中cudaChannelFormatKind可以是cudaChannelFormatKindSigned、cudaChannelFormatKindUnsigned或cudaChannelFormatKindFloat之一。

另请参阅：

cudaCreateChannelDesc ( C++ API), cudaGetChannelDesc, cudaCreateTextureObject, cudaCreateSurfaceObject

__host__ cudaError_t cudaCreateTextureObject ( cudaTextureObject_t* pTexObject, const cudaResourceDesc* pResDesc, const cudaTextureDesc* pTexDesc, const cudaResourceViewDesc* pResViewDesc )

创建一个纹理对象。

参数

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

cudaSuccess, cudaErrorInvalidValue

描述

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

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

cudaResourceDesc 结构体定义为：

‎        struct cudaResourceDesc {
                  enum cudaResourceType 
                  resType;
                  
                  union {
                      struct {
                          cudaArray_t 
                  array;
                      } array;
                      struct {
                          cudaMipmappedArray_t 
                  mipmap;
                      } mipmap;
                      struct {
                          void *devPtr;
                          struct cudaChannelFormatDesc 
                  desc;
                          size_t sizeInBytes;
                      } linear;
                      struct {
                          void *devPtr;
                          struct cudaChannelFormatDesc 
                  desc;
                          size_t width;
                          size_t height;
                          size_t pitchInBytes;
                      } pitch2D;
                  } res;
              };

where:

cudaResourceDesc::resType 指定要从中创建纹理的资源类型。CUresourceType定义为：

‎        enum cudaResourceType {
                  cudaResourceTypeArray          = 0x00,
                  cudaResourceTypeMipmappedArray = 0x01,
                  cudaResourceTypeLinear         = 0x02,
                  cudaResourceTypePitch2D        = 0x03
              };

如果cudaResourceDesc::resType设置为cudaResourceTypeArray，则cudaResourceDesc::res::array::array必须设置为有效的CUDA数组句柄。

如果cudaResourceDesc::resType设置为cudaResourceTypeMipmappedArray，则必须将cudaResourceDesc::res::mipmap::mipmap设置为有效的CUDA mipmapped数组句柄，且cudaTextureDesc::normalizedCoords必须设为true。

如果cudaResourceDesc::resType设置为cudaResourceTypeLinear，则cudaResourceDesc::res::linear::devPtr必须设置为一个有效的设备指针，该指针对齐到cudaDeviceProp::textureAlignment。cudaResourceDesc::res::linear::desc描述每个数组元素的格式和组件数量。cudaResourceDesc::res::linear::sizeInBytes指定数组的字节大小。线性地址范围内的元素总数不能超过cudaDeviceProp::maxTexture1DLinear。元素数量计算公式为(sizeInBytes / sizeof(desc))。

如果cudaResourceDesc::resType设置为cudaResourceTypePitch2D，则cudaResourceDesc::res::pitch2D::devPtr必须设置为一个有效的设备指针，该指针对齐到cudaDeviceProp::textureAlignment。cudaResourceDesc::res::pitch2D::desc描述每个数组元素的格式和组件数量。cudaResourceDesc::res::pitch2D::width和cudaResourceDesc::res::pitch2D::height分别指定数组的宽度和高度（以元素为单位），且不能超过cudaDeviceProp::maxTexture2DLinear[0]和cudaDeviceProp::maxTexture2DLinear[1]。cudaResourceDesc::res::pitch2D::pitchInBytes以字节为单位指定两行之间的间距，并且必须对齐到cudaDeviceProp::texturePitchAlignment。间距不能超过cudaDeviceProp::maxTexture2DLinear[2]。

cudaTextureDesc 结构体定义为

‎        struct cudaTextureDesc {
                  enum cudaTextureAddressMode 
                  addressMode[3];
                  enum cudaTextureFilterMode  
                  filterMode;
                  enum cudaTextureReadMode    
                  readMode;
                  int                         sRGB;
                  float                       borderColor[4];
                  int                         normalizedCoords;
                  unsigned int                maxAnisotropy;
                  enum cudaTextureFilterMode  
                  mipmapFilterMode;
                  float                       mipmapLevelBias;
                  float                       minMipmapLevelClamp;
                  float                       maxMipmapLevelClamp;
                  int                         disableTrilinearOptimization;
                  int                         seamlessCubemap;
              };

where

cudaTextureDesc::addressMode 指定纹理数据每个维度的寻址模式。cudaTextureAddressMode 定义为：
```
‎        enum cudaTextureAddressMode {
                  cudaAddressModeWrap   = 0,
                  cudaAddressModeClamp  = 1,
                  cudaAddressModeMirror = 2,
                  cudaAddressModeBorder = 3
              };
```
如果cudaResourceDesc::resType是cudaResourceTypeLinear，则此设置将被忽略。此外，如果cudaTextureDesc::normalizedCoords设置为零，cudaAddressModeWrap和cudaAddressModeMirror将不被支持，并会自动切换为cudaAddressModeClamp。

cudaTextureDesc::filterMode 指定从纹理获取数据时使用的过滤模式。cudaTextureFilterMode 定义为：
```
‎        enum cudaTextureFilterMode {
                  cudaFilterModePoint  = 0,
                  cudaFilterModeLinear = 1
              };
```
如果 cudaResourceDesc::resType 是 cudaResourceTypeLinear，则此设置将被忽略。

cudaTextureDesc::readMode 指定是否应将整数数据转换为浮点数。cudaTextureReadMode 定义为：
```
‎        enum cudaTextureReadMode {
                  cudaReadModeElementType     = 0,
                  cudaReadModeNormalizedFloat = 1
              };
```
请注意，这仅适用于8位和16位整数格式。无论是否将此cudaTextureDesc::readMode设置为cudaReadModeNormalizedFloat，32位整数格式都不会被提升。

cudaTextureDesc::sRGB 指定在纹理获取期间是否应执行sRGB到线性的转换。

cudaTextureDesc::borderColor 指定颜色的浮点数值。其中：cudaTextureDesc::borderColor[0] 包含'R'值，cudaTextureDesc::borderColor[1] 包含'G'值，cudaTextureDesc::borderColor[2] 包含'B'值，cudaTextureDesc::borderColor[3] 包含'A'值。请注意，使用整数边框颜色值的应用程序需要将这些值进行转换为浮点数。这些值仅在cudaTextureDesc::addressMode指定的寻址模式为cudaAddressModeBorder时设置。

cudaTextureDesc::normalizedCoords 指定纹理坐标是否会被归一化。

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

cudaTextureDesc::mipmapFilterMode 指定当计算的mipmap层级位于两个已定义的mipmap层级之间时使用的过滤模式。

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

cudaTextureDesc::minMipmapLevelClamp 指定了mipmap级别范围的下限，用于限制访问范围。

cudaTextureDesc::maxMipmapLevelClamp 指定了用于限制访问的mipmap级别范围的上限值。

cudaTextureDesc::disableTrilinearOptimization 指定是否禁用三线性过滤优化。

cudaTextureDesc::seamlessCubemap 指定是否启用无缝立方体贴图过滤。此标志仅当底层资源是使用cudaArrayCubemap标志创建的CUDA数组或CUDA多级渐远纹理数组时才能指定。当启用无缝立方体贴图过滤时，cudaTextureDesc::addressMode指定的纹理寻址模式将被忽略。相反，如果cudaTextureDesc::filterMode设置为cudaFilterModePoint，则所有维度都将应用cudaAddressModeClamp寻址模式。如果cudaTextureDesc::filterMode设置为cudaFilterModeLinear，则在沿立方体面边界采样时将执行无缝立方体贴图过滤。

cudaResourceViewDesc 结构体定义为

‎        struct cudaResourceViewDesc {
                  enum cudaResourceViewFormat 
                  format;
                  size_t                      width;
                  size_t                      height;
                  size_t                      depth;
                  unsigned int                firstMipmapLevel;
                  unsigned int                lastMipmapLevel;
                  unsigned int                firstLayer;
                  unsigned int                lastLayer;
              };

where:

cudaResourceViewDesc::format 指定应如何解释CUDA数组或CUDA多级渐远纹理数组中包含的数据。请注意，这可能导致纹理数据大小发生变化。如果资源视图格式是块压缩格式，则底层CUDA数组或CUDA多级渐远纹理数组必须具有32位无符号整数格式，并根据块压缩格式包含2或4个通道。例如，BC1和BC4要求底层CUDA数组具有2通道的32位无符号整数格式。其他BC格式要求底层资源具有相同的32位无符号整数格式，但需包含4个通道。

cudaResourceViewDesc::width 指定纹理数据的新宽度。如果资源视图格式是块压缩格式，该值必须是资源原始宽度的4倍。对于非块压缩格式，该值必须与原始资源保持一致。

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

cudaResourceViewDesc::depth 指定纹理数据的新深度值。该数值必须与原始资源保持一致。

cudaResourceViewDesc::firstMipmapLevel 指定最精细的mipmap层级。这将成为新的mipmap零级。对于非mipmap资源，该值必须为零。cudaTextureDesc::minMipmapLevelClamp 和 cudaTextureDesc::maxMipmapLevelClamp 将相对于此值进行计算。例如，如果firstMipmapLevel设为2，且minMipmapLevelClamp设为1.2，则实际最小mipmap层级限制将为3.2。

cudaResourceViewDesc::lastMipmapLevel 指定最不详细的mipmap层级。对于非mipmap资源，此值必须为零。

cudaResourceViewDesc::firstLayer 指定分层纹理的起始层索引。该值将成为新的零层。对于非分层资源，此值必须为零。

cudaResourceViewDesc::lastLayer 指定分层纹理的最后一层索引。对于非分层资源，此值必须为零。

Note:

请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaDestroyTextureObject, cuTexObjectCreate

__host__ cudaError_t cudaDestroyTextureObject ( cudaTextureObject_t texObject )

销毁一个纹理对象。

参数

texObject: - Texture object to destroy

cudaSuccess, cudaErrorInvalidValue

描述

销毁由texObject指定的纹理对象。

Note:

请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。
在此调用后使用该句柄将导致未定义行为。

另请参阅：

cudaCreateTextureObject, cuTexObjectDestroy

__host__ cudaError_t cudaGetChannelDesc ( cudaChannelFormatDesc* desc, cudaArray_const_t array )

获取数组的通道描述符。

参数

desc: - Channel format
array: - Memory array on device

cudaSuccess, cudaErrorInvalidValue

描述

在*desc中返回CUDA数组array的通道描述符。

Note:

请注意，此函数也可能返回之前异步启动的错误代码。
请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaCreateChannelDesc ( C API), cudaCreateTextureObject, cudaCreateSurfaceObject

__host__ cudaError_t cudaGetTextureObjectResourceDesc ( cudaResourceDesc* pResDesc, cudaTextureObject_t texObject )

返回纹理对象的资源描述符。

参数

pResDesc: - Resource descriptor
texObject: - Texture object

cudaSuccess, cudaErrorInvalidValue

描述

返回由texObject指定的纹理对象的资源描述符。

Note:

请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaCreateTextureObject, cuTexObjectGetResourceDesc

__host__ cudaError_t cudaGetTextureObjectResourceViewDesc ( cudaResourceViewDesc* pResViewDesc, cudaTextureObject_t texObject )

返回纹理对象的资源视图描述符。

参数

pResViewDesc: - Resource view descriptor
texObject: - Texture object

cudaSuccess, cudaErrorInvalidValue

描述

返回由texObject指定的纹理对象的资源视图描述符。如果未指定资源视图，则返回cudaErrorInvalidValue。

Note:

请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaCreateTextureObject, cuTexObjectGetResourceViewDesc

__host__ cudaError_t cudaGetTextureObjectTextureDesc ( cudaTextureDesc* pTexDesc, cudaTextureObject_t texObject )

返回纹理对象的纹理描述符。

参数

pTexDesc: - Texture descriptor
texObject: - Texture object

cudaSuccess, cudaErrorInvalidValue

描述

返回由texObject指定的纹理对象的纹理描述符。

Note:

请注意，如果此调用尝试初始化CUDA RT内部状态，该函数也可能返回cudaErrorInitializationError、cudaErrorInsufficientDriver或cudaErrorNoDevice。
请注意，根据cudaStreamAddCallback的规定，回调函数中不得调用任何CUDA函数。在这种情况下，可能会（但不保证）返回cudaErrorNotPermitted作为诊断信息。

另请参阅：

cudaCreateTextureObject, cuTexObjectGetTextureDesc