Forge 3d Picking

3D Picking

Add GPU-based object picking to an SDL GPU project. This skill covers two picking methods (color-ID and stencil-ID), GPU-to-CPU data transfer with SDL_DownloadFromGPUTexture, transfer buffer readback, and stencil outline selection highlighting.

Based on GPU Lesson 37.

When to use

• You need to identify which object the user clicked on in a 3D scene
• You want pixel-perfect selection without CPU-side ray casting
• You need to highlight selected objects with a visible outline
• You want to read data back from the GPU to the CPU

Color-ID picking pipeline

Color-ID picking renders each object with a unique flat color to an offscreen texture, then reads back the single pixel under the cursor to identify the object. This is the recommended approach — it is portable, supports up to 65,535 objects, and the RGBA readback has a consistent byte layout across all GPU backends.

Index-to-color encoding

/* Convert object index to a unique RGB color.
 * Index 0 maps to ID 1 (background is (0,0,0) = no object). */
static void index_to_color(int index, float *r, float *g, float *b)
{
    int id = index + 1;
    *r = (float)((id >> 0) & 0xFF) / 255.0f;
    *g = (float)((id >> 8) & 0xFF) / 255.0f;
    *b = 0.0f;
}

/* Decode a read-back pixel back to an object index. Returns -1 for background. */
static int color_to_index(Uint8 r, Uint8 g, Uint8 b)
{
    (void)b;
    int id = (int)r | ((int)g << 8);
    if (id == 0) return -1;
    return id - 1;
}

Offscreen render target

Create an R8G8B8A8_UNORM texture as the color-ID render target. Do not use the swapchain format — you need a known pixel layout for reliable CPU readback. Also create a separate depth buffer for occlusion:

/* Color-ID offscreen target */
SDL_GPUTextureCreateInfo ci;
SDL_zero(ci);
ci.type   = SDL_GPU_TEXTURETYPE_2D;
ci.format = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;
ci.width  = window_w;
ci.height = window_h;
ci.layer_count_or_depth = 1;
ci.num_levels = 1;
ci.usage  = SDL_GPU_TEXTUREUSAGE_COLOR_TARGET;
SDL_GPUTexture *id_texture = SDL_CreateGPUTexture(device, &ci);

/* ID pass depth buffer — separate from the main scene depth */
SDL_GPUTextureCreateInfo depth_ci;
SDL_zero(depth_ci);
depth_ci.type   = SDL_GPU_TEXTURETYPE_2D;
depth_ci.format = depth_stencil_fmt;  /* D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT */
depth_ci.width  = window_w;
depth_ci.height = window_h;
depth_ci.layer_count_or_depth = 1;
depth_ci.num_levels = 1;
depth_ci.usage  = SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET;
SDL_GPUTexture *id_depth = SDL_CreateGPUTexture(device, &depth_ci);

ID pass shaders

The vertex shader only needs MVP — no lighting outputs:

cbuffer IdVertUniforms : register(b0, space1)
{
    column_major float4x4 mvp;
};

struct VSInput
{
    float3 position : TEXCOORD0;
    float3 normal   : TEXCOORD1;  /* unused — must match vertex layout */
};

float4 main(VSInput input) : SV_Position
{
    return mul(mvp, float4(input.position, 1.0));
}

The fragment shader outputs the flat ID color:

cbuffer IdFragUniforms : register(b0, space3)
{
    float4 id_color;
};

float4 main(float4 pos : SV_Position) : SV_Target
{
    return id_color;
}

ID pipeline configuration

SDL_GPUColorTargetDescription ct;
SDL_zero(ct);
ct.format = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM;

SDL_GPUGraphicsPipelineCreateInfo pi;
SDL_zero(pi);
pi.vertex_shader   = id_pass_vert;
pi.fragment_shader = id_pass_frag;
pi.vertex_input_state = scene_vis;  /* same vertex layout as scene */
pi.primitive_type = SDL_GPU_PRIMITIVETYPE_TRIANGLELIST;

pi.rasterizer_state.fill_mode = SDL_GPU_FILLMODE_FILL;
pi.rasterizer_state.cull_mode = SDL_GPU_CULLMODE_BACK;
pi.rasterizer_state.front_face = SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE;

pi.depth_stencil_state.compare_op = SDL_GPU_COMPAREOP_LESS;
pi.depth_stencil_state.enable_depth_test  = true;
pi.depth_stencil_state.enable_depth_write = true;
pi.depth_stencil_state.enable_stencil_test = false;

pi.target_info.color_target_descriptions = &ct;
pi.target_info.num_color_targets = 1;
pi.target_info.depth_stencil_format = depth_stencil_fmt;
pi.target_info.has_depth_stencil_target = true;

ID pass execution

Only run the ID pass on click frames to avoid wasting GPU time:

if (pick_pending && picking_method == PICK_COLOR_ID) {
    SDL_GPUColorTargetInfo id_color_target;
    SDL_zero(id_color_target);
    id_color_target.texture  = id_texture;
    id_color_target.load_op  = SDL_GPU_LOADOP_CLEAR;
    id_color_target.store_op = SDL_GPU_STOREOP_STORE;
    /* Clear to (0,0,0,0) — decodes to "no object" */

    SDL_GPUDepthStencilTargetInfo id_ds;
    SDL_zero(id_ds);
    id_ds.texture     = id_depth;
    id_ds.clear_depth = 1.0f;
    id_ds.load_op     = SDL_GPU_LOADOP_CLEAR;
    id_ds.store_op    = SDL_GPU_STOREOP_DONT_CARE;
    id_ds.cycle       = true;

    SDL_GPURenderPass *pass = SDL_BeginGPURenderPass(
        cmd, &id_color_target, 1, &id_ds);
    SDL_BindGPUGraphicsPipeline(pass, id_pipeline);

    for (int i = 0; i < object_count; i++) {
        mat4 mvp = mat4_multiply(cam_vp, object_models[i]);

        IdVertUniforms vu = { .mvp = mvp };
        SDL_PushGPUVertexUniformData(cmd, 0, &vu, sizeof(vu));

        float id_r, id_g, id_b;
        index_to_color(i, &id_r, &id_g, &id_b);
        IdFragUniforms fu = {{ id_r, id_g, id_b, 1.0f }};
        SDL_PushGPUFragmentUniformData(cmd, 0, &fu, sizeof(fu));

        /* Bind and draw object geometry */
        SDL_DrawGPUIndexedPrimitives(pass, idx_count, 1, 0, 0, 0);
    }
    SDL_EndGPURenderPass(pass);
}

GPU readback with SDL_DownloadFromGPUTexture

Transfer buffer for readback

Create a DOWNLOAD transfer buffer once at init. For color-ID picking (RGBA8), 4 bytes suffices. For stencil-ID picking, D32_FLOAT_S8_UINT needs 8 bytes per pixel. Use SDL_CalculateGPUTextureFormatSize to size correctly for either:

SDL_GPUTransferBufferCreateInfo xfer_ci;
SDL_zero(xfer_ci);
xfer_ci.usage = SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD;
/* Size for the larger format to support both color-ID and stencil-ID */
Uint32 color_bpp = SDL_CalculateGPUTextureFormatSize(SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM, 1, 1, 1);
Uint32 ds_bpp    = SDL_CalculateGPUTextureFormatSize(ds_format, 1, 1, 1);
xfer_ci.size     = (color_bpp > ds_bpp) ? color_bpp : ds_bpp;
SDL_GPUTransferBuffer *pick_readback = SDL_CreateGPUTransferBuffer(device, &xfer_ci);

Copy pass

Download a single pixel from the source texture into the transfer buffer:

SDL_GPUCopyPass *copy = SDL_BeginGPUCopyPass(cmd);

SDL_GPUTextureRegion src_region;
SDL_zero(src_region);
src_region.texture = id_texture;  /* or depth-stencil for stencil-ID */
src_region.x = (Uint32)pick_x;
src_region.y = (Uint32)pick_y;
src_region.w = 1;
src_region.h = 1;
src_region.d = 1;

SDL_GPUTextureTransferInfo dst_info;
SDL_zero(dst_info);
dst_info.transfer_buffer = pick_readback;
dst_info.offset = 0;

SDL_DownloadFromGPUTexture(copy, &src_region, &dst_info);
SDL_EndGPUCopyPass(copy);

Wait, map, and decode

After submitting the command buffer, wait for GPU completion before reading:

if (!SDL_SubmitGPUCommandBuffer(cmd)) {
    SDL_Log("SDL_SubmitGPUCommandBuffer failed: %s", SDL_GetError());
    return;
}
if (!SDL_WaitForGPUIdle(device)) {
    SDL_Log("SDL_WaitForGPUIdle failed: %s", SDL_GetError());
    return;
}

void *pixel_data = SDL_MapGPUTransferBuffer(device, pick_readback, false);
if (pixel_data) {
    Uint8 *bytes = (Uint8 *)pixel_data;
    int picked = color_to_index(bytes[0], bytes[1], bytes[2]);
    selected_object = (picked >= 0 && picked < object_count) ? picked : -1;
    SDL_UnmapGPUTransferBuffer(device, pick_readback);
}

Stencil-ID picking

An alternative that reuses the scene stencil buffer. Limited to 255 objects and has backend-dependent byte layout, but requires no extra render pass.

Pipeline setup

pi.depth_stencil_state.enable_stencil_test = true;
pi.depth_stencil_state.front_stencil_state = (SDL_GPUStencilOpState){
    .fail_op       = SDL_GPU_STENCILOP_KEEP,
    .pass_op       = SDL_GPU_STENCILOP_REPLACE,
    .depth_fail_op = SDL_GPU_STENCILOP_KEEP,
    .compare_op    = SDL_GPU_COMPAREOP_ALWAYS,
};
pi.depth_stencil_state.back_stencil_state =
    pi.depth_stencil_state.front_stencil_state;
pi.depth_stencil_state.write_mask   = 0xFF;
pi.depth_stencil_state.compare_mask = 0xFF;

Per-object stencil reference

for (int i = 0; i < object_count; i++) {
    SDL_SetGPUStencilReference(pass, (Uint8)(i + 1));
    /* ... draw object i ... */
}

D24S8 readback

Download from the depth-stencil texture instead of the ID texture. The stencil byte position varies by GPU vendor:

Uint8 stencil = bytes[3];
int picked = (int)stencil - 1;
if (picked < 0 || picked >= object_count) {
    stencil = bytes[0];  /* fallback for reversed byte order */
    picked = (int)stencil - 1;
}

Selection outline with stencil

Highlight the selected object using the two-pass stencil outline technique from Lesson 34:

Outline write pipeline

/* Pass 1: draw selected object, write stencil marker */
pi.depth_stencil_state.enable_stencil_test = true;
pi.depth_stencil_state.front_stencil_state = (SDL_GPUStencilOpState){
    .fail_op       = SDL_GPU_STENCILOP_KEEP,
    .pass_op       = SDL_GPU_STENCILOP_REPLACE,
    .depth_fail_op = SDL_GPU_STENCILOP_KEEP,
    .compare_op    = SDL_GPU_COMPAREOP_ALWAYS,
};
pi.depth_stencil_state.back_stencil_state =
    pi.depth_stencil_state.front_stencil_state;
pi.depth_stencil_state.write_mask   = 0xFF;
pi.depth_stencil_state.compare_mask = 0xFF;

Outline draw pipeline

/* Pass 2: draw scaled-up object where stencil != marker */
pi.depth_stencil_state.enable_depth_test  = false;
pi.depth_stencil_state.enable_depth_write = false;
pi.depth_stencil_state.enable_stencil_test = true;
pi.depth_stencil_state.front_stencil_state = (SDL_GPUStencilOpState){
    .fail_op       = SDL_GPU_STENCILOP_KEEP,
    .pass_op       = SDL_GPU_STENCILOP_KEEP,
    .depth_fail_op = SDL_GPU_STENCILOP_KEEP,
    .compare_op    = SDL_GPU_COMPAREOP_NOT_EQUAL,
};
pi.depth_stencil_state.back_stencil_state =
    pi.depth_stencil_state.front_stencil_state;
pi.depth_stencil_state.write_mask   = 0x00;  /* don't modify stencil */
pi.depth_stencil_state.compare_mask = 0xFF;
pi.rasterizer_state.cull_mode = SDL_GPU_CULLMODE_NONE;

Outline rendering

#define STENCIL_OUTLINE  200  /* high value to avoid picking collisions */
#define OUTLINE_SCALE    1.04f

/* Outline pass: LOAD color + depth, CLEAR stencil */
SDL_GPUColorTargetInfo outline_color = {
    .texture  = swapchain_tex,
    .load_op  = SDL_GPU_LOADOP_LOAD,
    .store_op = SDL_GPU_STOREOP_STORE,
};
SDL_GPUDepthStencilTargetInfo outline_ds = {
    .texture          = main_depth,
    .load_op          = SDL_GPU_LOADOP_LOAD,
    .store_op         = SDL_GPU_STOREOP_DONT_CARE,
    .stencil_load_op  = SDL_GPU_LOADOP_CLEAR,
    .stencil_store_op = SDL_GPU_STOREOP_DONT_CARE,
    .clear_stencil    = 0,
};

SDL_GPURenderPass *pass = SDL_BeginGPURenderPass(
    cmd, &outline_color, 1, &outline_ds);

/* Step 1: draw object normally, write stencil marker */
SDL_BindGPUGraphicsPipeline(pass, outline_write_pipeline);
SDL_SetGPUStencilReference(pass, STENCIL_OUTLINE);
/* ... push uniforms, draw selected object ... */

/* Step 2: draw scaled-up object with NOT_EQUAL stencil */
SDL_BindGPUGraphicsPipeline(pass, outline_draw_pipeline);
SDL_SetGPUStencilReference(pass, STENCIL_OUTLINE);

mat4 outline_model = mat4_multiply(
    mat4_translate(object_position),
    mat4_scale_uniform(object_scale * OUTLINE_SCALE));
/* ... push outline uniforms (solid color), draw ... */

SDL_EndGPURenderPass(pass);

Key API calls

• SDL_CreateGPUTransferBuffer() with DOWNLOAD usage — CPU-readable staging buffer for GPU-to-CPU data transfer
• SDL_DownloadFromGPUTexture() — copy a texture region into a transfer buffer (runs inside a copy pass)
• SDL_WaitForGPUIdle() — block until all submitted GPU work completes
• SDL_MapGPUTransferBuffer() / SDL_UnmapGPUTransferBuffer() — access the downloaded pixel data on the CPU
• SDL_SetGPUStencilReference() — set per-draw stencil reference value for stencil-ID picking and outline rendering

Common mistakes

• Using the swapchain format for the ID texture — The swapchain format varies by platform and may be sRGB, which distorts the ID color encoding. Always use R8G8B8A8_UNORM for the ID texture.
• Missing depth buffer on the ID pass — Without its own depth buffer, the ID pass renders all objects without occlusion. Background objects overdraw foreground objects, producing incorrect pick results.
• Reading transfer buffer before GPU completion — The download is asynchronous. Reading the transfer buffer before SDL_WaitForGPUIdle (or fence completion) returns stale or garbage data.
• Forgetting to clear stencil for the outline pass — If the outline pass reuses stencil values from the scene pass (stencil-ID mode), the outline comparison will fail. Clear stencil at the start of the outline render pass.
• Stencil reference collision — If the outline marker value (e.g., 200) overlaps with stencil-ID object indices (1-N), the outline will not render correctly for those objects. Use a high marker value well above your object count.
• Running the ID pass every frame — The ID pass re-renders the entire scene. Running it every frame doubles the draw call count. Only run it on click frames unless you specifically need hover detection.

Cross-references

• GPU Lesson 37 — 3D Picking for the full walkthrough
• GPU Lesson 34 — Stencil Testing for the stencil outline technique
• GPU Lesson 36 — Edge Detection for alternative stencil patterns
• GPU Lesson 06 — Depth & 3D for depth buffer fundamentals