Mesh Loading — OBJ Parsing, Textured Rendering, Camera

This skill teaches how to load and render 3D models from Wavefront OBJ files. It builds on textures-and-samplers (Lesson 04), mipmaps (Lesson 05), depth-and-3d (Lesson 06), and camera-and-input (Lesson 07).

When to use

• Loading 3D models from OBJ files
• Rendering textured meshes with a camera
• Parsing vertex positions, normals, and UV coordinates from files
• Setting up non-indexed rendering (de-indexed vertices)
• Combining texture loading + mipmaps + depth testing + camera in one app

Key API calls (ordered)

1. forge_obj_load(path, &mesh) — parse OBJ into de-indexed vertex array
2. SDL_CreateGPUBuffer + transfer upload — upload vertices to GPU
3. SDL_LoadSurface + SDL_ConvertSurface — load PNG texture
4. SDL_CreateGPUTexture with SAMPLER | COLOR_TARGET — mipmapped texture
5. SDL_GenerateMipmapsForGPUTexture — auto-generate mip chain
6. SDL_CreateGPUSampler — trilinear, REPEAT address mode
7. SDL_CreateGPUGraphicsPipeline — 3 vertex attributes, depth test, back-face cull
8. SDL_BindGPUFragmentSamplers — bind diffuse texture + sampler
9. SDL_DrawGPUPrimitives — non-indexed draw (de-indexed vertices)

Libraries

c
1#include "obj/forge_obj.h"     /* OBJ parser */
2#include "math/forge_math.h"   /* vectors, matrices, quaternions */

Code template

Loading the mesh

c
1/* Build path relative to executable */
2const char *base_path = SDL_GetBasePath();
3char obj_path[512];
4SDL_snprintf(obj_path, sizeof(obj_path), "%smodels/model.obj", base_path);
5
6ForgeObjMesh mesh;
7if (!forge_obj_load(obj_path, &mesh)) {
8    SDL_Log("Failed to load model");
9    return SDL_APP_FAILURE;
10}
11
12/* Upload to GPU vertex buffer via transfer buffer */
13Uint32 vertex_data_size = mesh.vertex_count * (Uint32)sizeof(ForgeObjVertex);
14/* ... standard transfer buffer pattern from Lesson 02 ... */
15
16Uint32 mesh_vertex_count = mesh.vertex_count;
17forge_obj_free(&mesh);  /* CPU-side data no longer needed */

Loading texture with mipmaps

c
1SDL_Surface *surface = SDL_LoadSurface(tex_path);
2SDL_Surface *converted = SDL_ConvertSurface(surface, SDL_PIXELFORMAT_ABGR8888);
3SDL_DestroySurface(surface);
4
5int num_levels = (int)forge_log2f((float)converted->w) + 1;
6
7SDL_GPUTextureCreateInfo tex_info;
8SDL_zero(tex_info);
9tex_info.type     = SDL_GPU_TEXTURETYPE_2D;
10tex_info.format   = SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB;
11tex_info.usage    = SDL_GPU_TEXTUREUSAGE_SAMPLER | SDL_GPU_TEXTUREUSAGE_COLOR_TARGET;
12tex_info.width    = converted->w;
13tex_info.height   = converted->h;
14tex_info.num_levels = num_levels;
15/* ... upload base level, then: */
16SDL_GenerateMipmapsForGPUTexture(cmd, texture);

Vertex layout (3 attributes)

c
1/* ForgeObjVertex: position (float3) + normal (float3) + uv (float2) */
2
3vertex_attributes[0].location = 0;  /* TEXCOORD0 = position */
4vertex_attributes[0].format   = SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3;
5vertex_attributes[0].offset   = offsetof(ForgeObjVertex, position);
6
7vertex_attributes[1].location = 1;  /* TEXCOORD1 = normal */
8vertex_attributes[1].format   = SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3;
9vertex_attributes[1].offset   = offsetof(ForgeObjVertex, normal);
10
11vertex_attributes[2].location = 2;  /* TEXCOORD2 = uv */
12vertex_attributes[2].format   = SDL_GPU_VERTEXELEMENTFORMAT_FLOAT2;
13vertex_attributes[2].offset   = offsetof(ForgeObjVertex, uv);

Rendering (non-indexed)

c
1SDL_BindGPUVertexBuffers(pass, 0, &vertex_binding, 1);
2
3SDL_GPUTextureSamplerBinding tex_binding;
4SDL_zero(tex_binding);
5tex_binding.texture = diffuse_texture;
6tex_binding.sampler = sampler;
7SDL_BindGPUFragmentSamplers(pass, 0, &tex_binding, 1);
8
9/* Non-indexed draw — de-indexed vertices, every 3 form a triangle */
10SDL_DrawGPUPrimitives(pass, mesh_vertex_count, 1, 0, 0);

HLSL shaders

Vertex shader:

hlsl
1cbuffer Uniforms : register(b0, space1) { column_major float4x4 mvp; };
2
3struct VSInput {
4    float3 position : TEXCOORD0;
5    float3 normal   : TEXCOORD1;
6    float2 uv       : TEXCOORD2;
7};
8
9struct VSOutput {
10    float4 position : SV_Position;
11    float2 uv       : TEXCOORD0;
12};
13
14VSOutput main(VSInput input) {
15    VSOutput output;
16    output.position = mul(mvp, float4(input.position, 1.0));
17    output.uv = input.uv;
18    return output;
19}

Fragment shader:

hlsl
1Texture2D    diffuse_tex : register(t0, space2);
2SamplerState smp         : register(s0, space2);
3
4float4 main(float4 pos : SV_Position, float2 uv : TEXCOORD0) : SV_Target {
5    return diffuse_tex.Sample(smp, uv);
6}

Common mistakes

1. Forgetting UV flip — OBJ uses V=0 at bottom; GPU uses V=0 at top. The forge_obj.h parser handles this automatically (1.0 - v).

2. Using indexed draw for de-indexed mesh — Use SDL_DrawGPUPrimitives, not SDL_DrawGPUIndexedPrimitives, since vertices are already expanded.

3. Wrong pixel format — SDL_LoadSurface may return any format. Always convert to SDL_PIXELFORMAT_ABGR8888 for GPU R8G8B8A8.

4. Missing COLOR_TARGET usage — Required for mipmap generation. Without it, SDL_GenerateMipmapsForGPUTexture silently fails.

5. Not copying model files in CMake — The OBJ and texture must be next to the executable. Use add_custom_command(POST_BUILD ...) to copy them.

6. Loading JPG — SDL_LoadSurface only supports BMP and PNG. Convert JPG textures to PNG first (e.g. with Python Pillow).

CMakeLists.txt pattern

cmake
1# Copy model files next to executable
2add_custom_command(TARGET my-target POST_BUILD
3    COMMAND ${CMAKE_COMMAND} -E make_directory
4        $<TARGET_FILE_DIR:my-target>/models/model-name
5    COMMAND ${CMAKE_COMMAND} -E copy_if_different
6        ${CMAKE_CURRENT_SOURCE_DIR}/models/model-name/model.obj
7        $<TARGET_FILE_DIR:my-target>/models/model-name/model.obj
8    COMMAND ${CMAKE_COMMAND} -E copy_if_different
9        ${CMAKE_CURRENT_SOURCE_DIR}/models/model-name/texture.png
10        $<TARGET_FILE_DIR:my-target>/models/model-name/texture.png
11)

References

• GPU Lesson 08 — Loading a Mesh
• GPU Lesson 04 — Textures & Samplers
• GPU Lesson 05 — Mipmaps
• GPU Lesson 07 — Camera & Input
• OBJ Parser Library