CUDA Runtime API (PDF) - v9.2.88 (older) - Last updated April 12, 2018 - Send Feedback

## 4.23. Texture Reference Management

This section describes the low level texture reference management functions of the CUDA runtime application programming interface.

Some functions have overloaded C++ API template versions documented separately in the C++ API Routines module.

### Functions

__host__ ​cudaError_t cudaBindTexture ( size_t* offset, const textureReference* texref, const void* devPtr, const cudaChannelFormatDesc* desc, size_t size = UINT_MAX )
  Binds a memory area to a texture.
__host__ ​cudaError_t cudaBindTexture2D ( size_t* offset, const textureReference* texref, const void* devPtr, const cudaChannelFormatDesc* desc, size_t width, size_t height, size_t pitch )
  Binds a 2D memory area to a texture.
__host__ ​cudaError_t cudaBindTextureToArray ( const textureReference* texref, cudaArray_const_t array, const cudaChannelFormatDesc* desc )
  Binds an array to a texture.
__host__ ​cudaError_t cudaBindTextureToMipmappedArray ( const textureReference* texref, cudaMipmappedArray_const_t mipmappedArray, const cudaChannelFormatDesc* desc )
  Binds a mipmapped array to a texture.
__host__ ​cudaChannelFormatDesc cudaCreateChannelDesc ( int x, int y, int z, int w, cudaChannelFormatKind f )
  Returns a channel descriptor using the specified format.
__host__ ​cudaError_t cudaGetChannelDesc ( cudaChannelFormatDesc* desc, cudaArray_const_t array )
  Get the channel descriptor of an array.
__host__ ​cudaError_t cudaGetTextureAlignmentOffset ( size_t* offset, const textureReference* texref )
  Get the alignment offset of a texture.
__host__ ​cudaError_t cudaGetTextureReference ( const textureReference** texref, const void* symbol )
  Get the texture reference associated with a symbol.
__host__ ​cudaError_t cudaUnbindTexture ( const textureReference* texref )
  Unbinds a texture.

### Functions

__host__ ​cudaError_t cudaBindTexture ( size_t* offset, const textureReference* texref, const void* devPtr, const cudaChannelFormatDesc* desc, size_t size = UINT_MAX )
  Binds a memory area to a texture.

  ###### Parameters

  `offset`
    - Offset in bytes
  `texref`
    - Texture to bind
  `devPtr`
    - Memory area on device
  `desc`
    - Channel format
  `size`
    - Size of the memory area pointed to by devPtr

  ###### Returns

  cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidTexture

  ###### Description

  Binds `size` bytes of the memory area pointed to by `devPtr` to the texture reference `texref`. `desc` describes how the memory is interpreted when fetching values from the texture. Any memory previously bound to `texref` is unbound.

  Since the hardware enforces an alignment requirement on texture base addresses, cudaBindTexture() returns in `*offset` a byte offset that must be applied to texture fetches in order to read from the desired memory. This offset must be divided by the texel size and passed to kernels that read from the texture so they can be applied to the tex1Dfetch() function. If the device memory pointer was returned from cudaMalloc(), the offset is guaranteed to be 0 and NULL may be passed as the `offset` parameter.

  The total number of elements (or texels) in the linear address range cannot exceed cudaDeviceProp::maxTexture1DLinear[0]. The number of elements is computed as (`size` / elementSize), where elementSize is determined from `desc`.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetChannelDesc, cudaGetTextureReference, cudaBindTexture ( C++ API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C API), cudaUnbindTexture ( C API), cudaGetTextureAlignmentOffset ( C API), cuTexRefSetAddress, cuTexRefSetAddressMode, cuTexRefSetFormat, cuTexRefSetFlags, cuTexRefSetBorderColor

__host__ ​cudaError_t cudaBindTexture2D ( size_t* offset, const textureReference* texref, const void* devPtr, const cudaChannelFormatDesc* desc, size_t width, size_t height, size_t pitch )
  Binds a 2D memory area to a texture.

  ###### Parameters

  `offset`
    - Offset in bytes
  `texref`
    - Texture reference to bind
  `devPtr`
    - 2D memory area on device
  `desc`
    - Channel format
  `width`
    - Width in texel units
  `height`
    - Height in texel units
  `pitch`
    - Pitch in bytes

  ###### Returns

  cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidTexture

  ###### Description

  Binds the 2D memory area pointed to by `devPtr` to the texture reference `texref`. The size of the area is constrained by `width` in texel units, `height` in texel units, and `pitch` in byte units. `desc` describes how the memory is interpreted when fetching values from the texture. Any memory previously bound to `texref` is unbound.

  Since the hardware enforces an alignment requirement on texture base addresses, cudaBindTexture2D() returns in `*offset` a byte offset that must be applied to texture fetches in order to read from the desired memory. This offset must be divided by the texel size and passed to kernels that read from the texture so they can be applied to the tex2D() function. If the device memory pointer was returned from cudaMalloc(), the offset is guaranteed to be 0 and NULL may be passed as the `offset` parameter.

  `width` and `height`, which are specified in elements (or texels), cannot exceed cudaDeviceProp::maxTexture2DLinear[0] and cudaDeviceProp::maxTexture2DLinear[1] respectively. `pitch`, which is specified in bytes, cannot exceed cudaDeviceProp::maxTexture2DLinear[2].

  The driver returns cudaErrorInvalidValue if `pitch` is not a multiple of cudaDeviceProp::texturePitchAlignment.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetChannelDesc, cudaGetTextureReference, cudaBindTexture ( C API), cudaBindTexture2D ( C++ API), cudaBindTexture2D ( C++ API, inherited channel descriptor), cudaBindTextureToArray ( C API), cudaBindTextureToArray ( C API), cudaGetTextureAlignmentOffset ( C API), cuTexRefSetAddress2D, cuTexRefSetFormat, cuTexRefSetFlags, cuTexRefSetAddressMode, cuTexRefSetBorderColor

__host__ ​cudaError_t cudaBindTextureToArray ( const textureReference* texref, cudaArray_const_t array, const cudaChannelFormatDesc* desc )
  Binds an array to a texture.

  ###### Parameters

  `texref`
    - Texture to bind
  `array`
    - Memory array on device
  `desc`
    - Channel format

  ###### Returns

  cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidTexture

  ###### Description

  Binds the CUDA array `array` to the texture reference `texref`. `desc` describes how the memory is interpreted when fetching values from the texture. Any CUDA array previously bound to `texref` is unbound.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetChannelDesc, cudaGetTextureReference, cudaBindTexture ( C API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C++ API), cudaUnbindTexture ( C API), cudaGetTextureAlignmentOffset ( C API), cuTexRefSetArray, cuTexRefSetFormat, cuTexRefSetFlags, cuTexRefSetAddressMode, cuTexRefSetFilterMode, cuTexRefSetBorderColor, cuTexRefSetMaxAnisotropy

__host__ ​cudaError_t cudaBindTextureToMipmappedArray ( const textureReference* texref, cudaMipmappedArray_const_t mipmappedArray, const cudaChannelFormatDesc* desc )
  Binds a mipmapped array to a texture.

  ###### Parameters

  `texref`
    - Texture to bind
  `mipmappedArray`
    - Memory mipmapped array on device
  `desc`
    - Channel format

  ###### Returns

  cudaSuccess, cudaErrorInvalidValue, cudaErrorInvalidTexture

  ###### Description

  Binds the CUDA mipmapped array `mipmappedArray` to the texture reference `texref`. `desc` describes how the memory is interpreted when fetching values from the texture. Any CUDA mipmapped array previously bound to `texref` is unbound.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetChannelDesc, cudaGetTextureReference, cudaBindTexture ( C API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C++ API), cudaUnbindTexture ( C API), cudaGetTextureAlignmentOffset ( C API), cuTexRefSetMipmappedArray, cuTexRefSetMipmapFilterMode cuTexRefSetMipmapLevelClamp, cuTexRefSetMipmapLevelBias, cuTexRefSetFormat, cuTexRefSetFlags, cuTexRefSetAddressMode, cuTexRefSetBorderColor, cuTexRefSetMaxAnisotropy

__host__ ​cudaChannelFormatDesc cudaCreateChannelDesc ( int x, int y, int z, int w, cudaChannelFormatKind f )
  Returns a channel descriptor using the specified format.

  ###### Parameters

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

  ###### Returns

  Channel descriptor with format `f`

  ###### Description

  Returns a channel descriptor with format `f` and number of bits of each component `x`, `y`, `z`, and `w`. The cudaChannelFormatDesc is defined as:

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

  where cudaChannelFormatKind is one of cudaChannelFormatKindSigned, cudaChannelFormatKindUnsigned, or cudaChannelFormatKindFloat.

  See also:

  cudaCreateChannelDesc ( C++ API), cudaGetChannelDesc, cudaGetTextureReference, cudaBindTexture ( C API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C API), cudaUnbindTexture ( C API), cudaGetTextureAlignmentOffset ( C API), cuTexRefSetFormat

__host__ ​cudaError_t cudaGetChannelDesc ( cudaChannelFormatDesc* desc, cudaArray_const_t array )
  Get the channel descriptor of an array.

  ###### Parameters

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

  ###### Returns

  cudaSuccess, cudaErrorInvalidValue

  ###### Description

  Returns in `*desc` the channel descriptor of the CUDA array `array`.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetTextureReference, cudaBindTexture ( C API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C API), cudaUnbindTexture ( C API), cudaGetTextureAlignmentOffset ( C API)

__host__ ​cudaError_t cudaGetTextureAlignmentOffset ( size_t* offset, const textureReference* texref )
  Get the alignment offset of a texture.

  ###### Parameters

  `offset`
    - Offset of texture reference in bytes
  `texref`
    - Texture to get offset of

  ###### Returns

  cudaSuccess, cudaErrorInvalidTexture, cudaErrorInvalidTextureBinding

  ###### Description

  Returns in `*offset` the offset that was returned when texture reference `texref` was bound.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetChannelDesc, cudaGetTextureReference, cudaBindTexture ( C API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C API), cudaUnbindTexture ( C API), cudaGetTextureAlignmentOffset ( C++ API)

__host__ ​cudaError_t cudaGetTextureReference ( const textureReference** texref, const void* symbol )
  Get the texture reference associated with a symbol.

  ###### Parameters

  `texref`
    - Texture reference associated with symbol
  `symbol`
    - Texture to get reference for

  ###### Returns

  cudaSuccess, cudaErrorInvalidTexture

  ###### Description

  Returns in `*texref` the structure associated to the texture reference defined by symbol `symbol`.

  Note:

  - Note that this function may also return error codes from previous, asynchronous launches.

  - Use of a string naming a variable as the `symbol` paramater was removed in CUDA 5.0.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetChannelDesc, cudaGetTextureAlignmentOffset ( C API), cudaBindTexture ( C API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C API), cudaUnbindTexture ( C API), cuModuleGetTexRef

__host__ ​cudaError_t cudaUnbindTexture ( const textureReference* texref )
  Unbinds a texture.

  ###### Parameters

  `texref`
    - Texture to unbind

  ###### Returns

  cudaSuccess, cudaErrorInvalidTexture

  ###### Description

  Unbinds the texture bound to `texref`. If `texref` is not currently bound, no operation is performed.

  Note:

  Note that this function may also return error codes from previous, asynchronous launches.

  See also:

  cudaCreateChannelDesc ( C API), cudaGetChannelDesc, cudaGetTextureReference, cudaBindTexture ( C API), cudaBindTexture2D ( C API), cudaBindTextureToArray ( C API), cudaUnbindTexture ( C++ API), cudaGetTextureAlignmentOffset ( C API)