CUDA 运行时 API :: CUDA 工具包文档

6.27. 纹理对象管理

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

函数

__host__ cudaChannelFormatDesc cudaCreateChannelDesc ( int x, int y, int z, int w, cudaChannelFormatKind f ): 返回使用指定格式的通道描述符。
__host__ cudaError_t cudaCreateTextureObject ( cudaTextureObject_t* pTexObject, const cudaResourceDesc* pResDesc, const cudaTextureDesc* pTexDesc, const cudaResourceViewDesc* pResViewDesc ): 创建纹理对象。
__host__ cudaError_t cudaDestroyTextureObject ( cudaTextureObject_t texObject ): 销毁纹理对象。
__host__ cudaError_t cudaGetChannelDesc ( cudaChannelFormatDesc* desc, cudaArray_const_t array ): 获取数组的通道描述符。
__host__ cudaError_t cudaGetTextureObjectResourceDesc ( cudaResourceDesc* pResDesc, cudaTextureObject_t texObject ): 返回纹理对象的资源描述符。
__host__ cudaError_t cudaGetTextureObjectResourceViewDesc ( cudaResourceViewDesc* pResViewDesc, cudaTextureObject_t texObject ): 返回纹理对象的资源视图描述符。
__host__ cudaError_t cudaGetTextureObjectTextureDesc ( cudaTextureDesc* pTexDesc, cudaTextureObject_t texObject ): 返回纹理对象的纹理描述符。

函数

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

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

参数

x: - X 分量
y: - Y 分量
z: - Z 分量
w: - W 分量
f: - 通道格式

返回值

具有格式的通道描述符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: - 要创建的纹理对象
pResDesc: - 资源描述符
pTexDesc: - 纹理描述符
pResViewDesc: - 资源视图描述符

返回值

cudaSuccess, cudaErrorInvalidValue

描述

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

纹理对象仅在计算能力为 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;
              };

其中

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;
              };

其中

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' 的值。请注意，使用整数边框颜色值的应用程序将需要将这些值 <reinterpret_cast> 转换为浮点数。仅当 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 mipmapped 数组时，才能指定此标志。启用无缝立方体贴图过滤后，将忽略 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;
              };

其中

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

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

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

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

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

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

cudaResourceViewDesc::firstLayer 指定分层纹理的第一个图层索引。这将是新的图层零。对于非分层资源，此值必须为零。

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

注意

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

另请参阅

cudaDestroyTextureObject, cuTexObjectCreate

__host__ cudaError_t cudaDestroyTextureObject ( cudaTextureObject_t texObject )

销毁纹理对象。

参数

texObject: - 要销毁的纹理对象

返回值

cudaSuccess, cudaErrorInvalidValue

描述

销毁由texObject.

注意

请注意，如果此调用尝试初始化内部 CUDA RT 状态，则此函数也可能返回 cudaErrorInitializationError、cudaErrorInsufficientDriver 或 cudaErrorNoDevice。
请注意，如 cudaStreamAddCallback 中所指定，不得从回调函数中调用任何 CUDA 函数。在这种情况，可能会（但不保证）返回 cudaErrorNotPermitted 作为诊断信息。
指定的纹理对象。在此调用之后使用句柄是未定义的行为。

另请参阅

cudaCreateTextureObject, cuTexObjectDestroy

__host__ cudaError_t cudaGetChannelDesc ( cudaChannelFormatDesc* desc, cudaArray_const_t array )

获取数组的通道描述符。

参数

desc: - 通道格式
array: - 设备上的内存数组

返回值

cudaSuccess, cudaErrorInvalidValue

描述

返回值在*descCUDA 数组的通道描述符array.

注意

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

另请参阅

cudaCreateChannelDesc ( C API), cudaCreateTextureObject, cudaCreateSurfaceObject

__host__ cudaError_t cudaGetTextureObjectResourceDesc ( cudaResourceDesc* pResDesc, cudaTextureObject_t texObject )

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

参数

pResDesc: - 资源描述符
texObject: - 纹理对象

返回值

cudaSuccess, cudaErrorInvalidValue

描述

返回由以下函数指定的纹理对象的资源描述符：texObject.

注意

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

另请参阅

cudaCreateTextureObject, cuTexObjectGetResourceDesc

__host__ cudaError_t cudaGetTextureObjectResourceViewDesc ( cudaResourceViewDesc* pResViewDesc, cudaTextureObject_t texObject )

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

参数

pResViewDesc: - 资源视图描述符
texObject: - 纹理对象

返回值

cudaSuccess, cudaErrorInvalidValue

描述

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

注意

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

另请参阅

cudaCreateTextureObject, cuTexObjectGetResourceViewDesc

__host__ cudaError_t cudaGetTextureObjectTextureDesc ( cudaTextureDesc* pTexDesc, cudaTextureObject_t texObject )

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

参数

pTexDesc: - 纹理描述符
texObject: - 纹理对象

返回值

cudaSuccess, cudaErrorInvalidValue

描述

返回由以下函数指定的纹理对象的纹理描述符：texObject.

注意

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

另请参阅

cudaCreateTextureObject, cuTexObjectGetTextureDesc