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
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
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
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
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, cuTexRefSetMipmapFilterModecuTexRefSetMipmapLevelClamp, 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

__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
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
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
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

Description

Unbinds the texture bound to texref.

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)