glDispatchCompute
Launches the current compute shader over a 3D grid of work groups.
Signature
void glDispatchCompute(GLuint num_groups_x, GLuint num_groups_y, GLuint num_groups_z);
How it works
A compute shader runs as many small groups of invocations. The shader declares the group size (layout(local_size_x = 16, local_size_y = 16) in;), and this call says how many groups to launch in each dimension. Total invocations = groups × local size.
To process a 1920×1080 image with 16×16 groups, launch ceil(1920/16) × ceil(1080/16) groups.
Parameters
Groups along X.
Groups along Y (1 for 1D work).
Groups along Z (1 for 1D/2D work).
Tips & pitfalls
Round up with (n + size - 1) / size, and guard in the shader with if (id.x >= width) return; for the extra invocations.
Results are not guaranteed visible to later commands until you call
glMemoryBarrier.
Errors
When the call is invalid it does nothing and sets an error, which glGetError returns:
- GL_INVALID_OPERATION
- No program with a compute shader is in use.
- GL_INVALID_VALUE
- A count exceeds GL_MAX_COMPUTE_WORK_GROUP_COUNT.
Example
1glUseProgram(blurProgram);
2glBindImageTexture(0, output, 0, GL_FALSE, 0, GL_WRITE_ONLY, GL_RGBA16F);
3glDispatchCompute((w + 15) / 16, (h + 15) / 16, 1);
4glMemoryBarrier(GL_SHADER_IMAGE_ACCESS_BARRIER_BIT);