Memory

Texture Memory and Surface Memory

Texture Memory and Surface Memory

CUDA provides hardware-accelerated texture memory (read-only, cached, with filtering) and surface memory (read-write image objects). Both are backed by global DRAM but accessed through a dedicated texture/surface cache optimized for 2D spatial locality.

Why Texture Cache?

Global memory cache (L1/L2) is optimized for 1D coalesced access. The texture cache is optimized for 2D spatial locality — if you read pixel (x, y), the hardware prefetches its neighbors. This helps image processing stencils where access patterns include (x±1, y±1) neighborhoods.

Additional hardware features:

  • ▸Automatic boundary handling: clamp, wrap, or mirror at image edges — no manual bounds checks
  • ▸Hardware bilinear/trilinear interpolation: free hardware interpolation between texels for float coordinates
  • ▸Normalized coordinates: address textures using [0.0, 1.0) regardless of actual dimensions

Texture Objects (CUDA 5.0+, Recommended)

The modern API uses opaque cudaTextureObject_t handles:

c
// Step 1: allocate a CUDA Array (optimal 2D tiled layout)
cudaArray_t cuArray;
cudaChannelFormatDesc chanDesc = cudaCreateChannelDesc<float>();
cudaMallocArray(&cuArray, &chanDesc, width, height);

// Step 2: copy host data into the array
cudaMemcpy2DToArray(cuArray, 0, 0, h_data,
                    width * sizeof(float), width * sizeof(float), height,
                    cudaMemcpyHostToDevice);

// Step 3: create resource descriptor and texture descriptor
cudaResourceDesc resDesc = {};
resDesc.resType         = cudaResourceTypeArray;
resDesc.res.array.array = cuArray;

cudaTextureDesc texDesc = {};
texDesc.addressMode[0]  = cudaAddressModeClamp;   // boundary handling: x
texDesc.addressMode[1]  = cudaAddressModeClamp;   // boundary handling: y
texDesc.filterMode      = cudaFilterModeLinear;    // bilinear interpolation
texDesc.readMode        = cudaReadModeElementType;
texDesc.normalizedCoords = 0;                      // use integer coordinates

// Step 4: create texture object
cudaTextureObject_t texObj;
cudaCreateTextureObject(&texObj, &resDesc, &texDesc, nullptr);
c
// In the kernel: read with tex2D
__global__ void blurKernel(cudaTextureObject_t tex, float *out, int W, int H) {
    int x = blockIdx.x * blockDim.x + threadIdx.x;
    int y = blockIdx.y * blockDim.y + threadIdx.y;
    if (x >= W || y >= H) return;

    // tex2D automatically clamps out-of-bounds (no if-guards needed)
    float sum = tex2D<float>(tex, x-1, y-1) + tex2D<float>(tex, x, y-1) + tex2D<float>(tex, x+1, y-1)
              + tex2D<float>(tex, x-1, y  ) + tex2D<float>(tex, x, y  ) + tex2D<float>(tex, x+1, y  )
              + tex2D<float>(tex, x-1, y+1) + tex2D<float>(tex, x, y+1) + tex2D<float>(tex, x+1, y+1);
    out[y * W + x] = sum / 9.0f;
}

Surface Memory (Read-Write Images)

Surface memory allows writes back to the CUDA Array in a kernel — useful for in-place image processing:

c
cudaSurfaceObject_t surfObj;
cudaResourceDesc surfDesc = {};
surfDesc.resType         = cudaResourceTypeArray;
surfDesc.res.array.array = cuArray;
cudaCreateSurfaceObject(&surfObj, &surfDesc);

// In kernel
__global__ void invertKernel(cudaSurfaceObject_t surf, int W, int H) {
    int x = blockIdx.x * blockDim.x + threadIdx.x;
    int y = blockIdx.y * blockDim.y + threadIdx.y;
    if (x >= W || y >= H) return;

    float val;
    surf2Dread(&val, surf, x * sizeof(float), y);  // read
    surf2Dwrite(1.0f - val, surf, x * sizeof(float), y);  // write
}

When to Use Texture vs. Global Memory

| Use texture/surface when | Use global memory when | |---|---| | 2D spatial access patterns (image stencils) | 1D coalesced access | | Need hardware clamping/wrapping at borders | Arbitrary read-write access | | Bilinear interpolation is useful | Integer indexing only | | Read-only data accessed irregularly | Data changes every kernel |

Cleanup

c
cudaDestroyTextureObject(texObj);
cudaDestroySurfaceObject(surfObj);
cudaFreeArray(cuArray);

// CODE EXAMPLE

example.cu
// 3×3 box blur using texture object — no manual boundary checks
#include <cuda_runtime.h>
#include <cstdio>

__global__ void boxBlur(cudaTextureObject_t tex,
                        float *out, int W, int H) {
    int x = blockIdx.x * blockDim.x + threadIdx.x;
    int y = blockIdx.y * blockDim.y + threadIdx.y;
    if (x >= W || y >= H) return;

    float sum = 0.f;
    for (int dy = -1; dy <= 1; dy++)
        for (int dx = -1; dx <= 1; dx++)
            sum += tex2D<float>(tex, x + dx, y + dy);  // clamp handles borders

    out[y * W + x] = sum * (1.f / 9.f);
}

int main() {
    const int W = 512, H = 512;
    const int N = W * H;

    // Allocate CUDA Array (2D tiled layout, optimal for texture cache)
    cudaArray_t arr;
    cudaChannelFormatDesc cd = cudaCreateChannelDesc<float>();
    cudaMallocArray(&arr, &cd, W, H);

    // Fill with test data (all 1s)
    float *h = new float[N];
    for (int i = 0; i < N; i++) h[i] = 1.f;
    cudaMemcpy2DToArray(arr, 0, 0, h, W*sizeof(float), W*sizeof(float), H, cudaMemcpyHostToDevice);

    // Create texture object
    cudaResourceDesc rd = {};
    rd.resType = cudaResourceTypeArray;
    rd.res.array.array = arr;

    cudaTextureDesc td = {};
    td.addressMode[0] = td.addressMode[1] = cudaAddressModeClamp;
    td.filterMode     = cudaFilterModePoint;   // nearest-neighbor
    td.readMode       = cudaReadModeElementType;
    td.normalizedCoords = 0;

    cudaTextureObject_t tex;
    cudaCreateTextureObject(&tex, &rd, &td, nullptr);

    float *d_out;
    cudaMalloc(&d_out, N * sizeof(float));

    dim3 block(16, 16), grid((W+15)/16, (H+15)/16);
    boxBlur<<<grid, block>>>(tex, d_out, W, H);
    cudaDeviceSynchronize();

    float h_out;
    cudaMemcpy(&h_out, d_out, sizeof(float), cudaMemcpyDeviceToHost);
    printf("out[0,0] = %.4f (expected 1.0)\n", h_out);

    cudaDestroyTextureObject(tex);
    cudaFreeArray(arr);
    cudaFree(d_out);
    delete[] h;
}

// TRY IT

GPU execution
main.cu
loading editor…