GPU Mesh Utilities (gpu.mesh)

Mesh related GPU helpers.

gpu.mesh.free_compute_resources(obj)

Free GPU compute resources (shaders, internal buffers) associated with the mesh owned by obj. This should be called to clean up after using gpu.mesh.scatter_positions_to_corners or gpu.mesh.run_compute_mesh.

This also resets internal flags like mesh.is_using_gpu_deform. obj may be an evaluated object or an original object (bpy.types.Object).

Parameters:

obj (bpy.types.Object) – Mesh owner object, evaluated or original.

Returns:

None.

Return type:

None

gpu.mesh.run_compute_mesh(obj, shader, bindings, config=None, dispatch_count=0)

Run a custom compute shader on a mesh.

Parameters:

• obj (bpy.types.Object) – Evaluated mesh object with a ready batch cache.

• shader (str) – GLSL compute shader source code.

• bindings (Sequence[tuple]) – Sequence of 5-tuples (binding_index, buffer, qualifier, type_name, bind_name).

• config (Callable | None) – Optional callable returning a Python dict for specialization constants and push constants.

• dispatch_count (int) – Number of invocations. If 0, defaults to mesh vertex count.

Binding tuples use the form:

(binding_index:int, buffer:GPUStorageBuf|GPUVertBuf|GPUUniformBuf|GPUIndexBuf|str|None, qualifier:str('read'|'write'|'read_write'), type_name:str, bind_name:str)

Notes about buffer:

• If buffer is a string token, it is resolved against the mesh batch cache VBOs.

• Supported tokens include 'Position', 'VBO::Position', 'CornerNormal' and 'VBO::CornerNormal'.

• Accepted Python buffer wrappers are gpu.types.GPUStorageBuf, gpu.types.GPUVertBuf, gpu.types.GPUUniformBuf (bound as SSBO), gpu.types.GPUIndexBuf (bound as SSBO), or None.

config callable behavior:

• Top-level entries with scalar values (int, float, bool) are treated as specialization constants and declared at shader creation time.

• A special key 'push_constants' may contain a dict mapping uniform names to values.

• Values can be float/int/bool or a sequence of floats/ints for arrays; they are applied immediately before dispatch via GPU_shader_uniform_*.

Example config callable (Python):

def config():
    return {
        'GRID_W': 128,
        'GRID_H': 128,
        'HEIGHT_SCALE': 1.0,
        'push_constants': {
            'u_time': 1.234,
            'u_spiral_strength': 0.5,
            'u_enabled': True,
            'u_offsets': [0.0, 1.0, 2.0],
        }
    }

Builtins injected automatically (topology accessors bound as int topo[] at binding 15):

int face_offsets(int i);
int corner_to_face(int i);
int corner_verts(int i);
int corner_tri(int tri_idx, int vert_idx);
int corner_tri_face(int i);
int2 edges(int i);
int corner_edges(int i);
int vert_to_face_offsets(int i);
int vert_to_face(int i);

Automatic specialization constants added by the runtime:

• int normals_domain (mesh-derived): 0 = vertex, 1 = face.

• int normals_hq: high-quality normals flag (0/1).

Returns:

Integer status: 0 = Success, 1 = NotReady (deferred), 2 = Error.

Return type:

int

gpu.mesh.scatter_positions_to_corners(obj, ssbo_positions, transform=None)

Scatter per-vertex positions (from user SSBO) to per-corner VBOs and recompute packed normals using the internal compute shader. The mesh VBOs (positions and normals) will be updated and ready for rendering.

NOTE: this function is non-blocking and may request the draw/cache system to rebuild mesh VBOs asynchronously. If the evaluated mesh currently uses a 3-component vertex format but the draw/cache needs a 4-component (float4) format, the function will tag the object for a geometry rebuild and return immediately. The actual VBO population and scatter will then occur on the next frame.

Because the operation can be deferred, callers that require the scatter to be completed synchronously should re-invoke this function on a later frame (for example using bpy.app.timers.register or from a modal operator) until the VBOs are populated. This C API does not block or force the draw/cache to populate VBOs synchronously.

Parameters:

• obj (bpy.types.Object) – Evaluated bpy.types.Object owning the mesh (use obj.evaluated_get(depsgraph)).

• ssbo_positions (gpu.types.GPUStorageBuf) – gpu.types.GPUStorageBuf containing vec4 per vertex (object-space positions).

• transform (gpu.types.GPUStorageBuf | None) – Optional gpu.types.GPUStorageBuf containing a mat4 (used as transform_mat[0]). If omitted, an identity mat4 is used.

Accepted buffer types (bindings passed to the high-level API):

• gpu.types.GPUStorageBuf (SSBO)

• gpu.types.GPUVertBuf (VBO wrapper)

• gpu.types.GPUUniformBuf (bound as SSBO via GPU_uniformbuf_bind_as_ssbo)

• gpu.types.GPUIndexBuf (bound as SSBO via GPU_indexbuf_bind_as_ssbo)

• string tokens resolving mesh VBOs (for example 'Position', 'VBO::Position', 'CornerNormal')

• None

GLSL helpers injected automatically (topology buffer bound as int topo[] at binding 15):

int face_offsets(int i);
int corner_to_face(int i);
int corner_verts(int i);
int corner_tri(int tri_idx, int vert_idx);
int corner_tri_face(int i);
int2 edges(int i);
int corner_edges(int i);
int vert_to_face_offsets(int i);
int vert_to_face(int i);

Specialization constants added automatically:

• int normals_domain: 0 = vertex normals, 1 = face normals (derived from mesh)

• int normals_hq: 0/1 high-quality normals flag (from scene perf_flag / workarounds)

Binding indices used by the builtin scatter shader (for reference):

• binding=0: positions_out[] (write, VBO::Position)

• binding=1: normals_out[] (write, VBO::CornerNormal)

• binding=2: positions_in[] (read, vec4 SSBO provided by caller)

• binding=3: transform_mat[] (read, mat4 SSBO)

• binding=15: topo[] (read, int SSBO injected automatically)

Returns:

None.

Return type:

None

Raises:

RuntimeError – On failure.