---
name: gpu_dispatch
kind: function
lang: cpp
domain: gfx
version: "1.0.0"
purity: impure
signature: "void dispatch_1d(int num, int local=64); void dispatch_2d(int w, int h, int lx=8, int ly=8); void dispatch_3d(int x, int y, int z, int lx=4, int ly=4, int lz=4); void barrier_storage(); void barrier_uniform(); void barrier_image(); void barrier_buffer_update(); void barrier_all()"
description: "Wrappers de glDispatchCompute con calculo automatico de workgroups (ceil(N/local)) y helpers de glMemoryBarrier para los casos comunes (storage, uniform, image, buffer update, all)."
tags: [opengl, compute, dispatch, barrier, gpu, gfx]
uses_functions: ["gl_loader_cpp_gfx"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [GL/gl.h, GL/glext.h]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/gfx/gpu_dispatch.cpp"
framework: opengl
params:
  - name: num_invocations
    desc: "Numero total de hilos deseados (1D). El wrapper calcula ceil(num/local_size_x) workgroups."
  - name: width
    desc: "Variante 2D: hilos en X."
  - name: height
    desc: "Variante 2D: hilos en Y."
  - name: x
    desc: "Variante 3D: hilos en X."
  - name: y
    desc: "Variante 3D: hilos en Y."
  - name: z
    desc: "Variante 3D: hilos en Z."
  - name: local_size_x
    desc: "Workgroup size en X. Debe coincidir con el layout(local_size_x=...) del shader compilado por gpu_compute_program."
  - name: local_size_y
    desc: "Workgroup size en Y (2D/3D)."
  - name: local_size_z
    desc: "Workgroup size en Z (3D)."
output: "Emite glDispatchCompute con los grupos calculados. No-op si algun parametro <= 0. Las funciones barrier_* emiten glMemoryBarrier con la mascara apropiada."
---

# gpu_dispatch

Despacho de computes y memory barriers. Pensado para usarse despues de `glUseProgram` + `ssbo_bind` + sets de uniforms.

## Patron tipico

```cpp
glUseProgram(prog);
fn::gfx::ssbo_bind(samples, 0);
fn::gfx::ssbo_bind(seeds,   1);
glUniform1ui(loc_count, N);

fn::gfx::dispatch_1d(N, /*local=*/64);
fn::gfx::barrier_storage();   // siguiente compute leera samples
```

## Encadenado de pases

```cpp
// Pass 1: muestrear
glUseProgram(p_sample);
fn::gfx::dispatch_1d(N, 64);
fn::gfx::barrier_storage();

// Pass 2: binning a histograma
glUseProgram(p_hist);
fn::gfx::dispatch_1d(N, 64);
fn::gfx::barrier_buffer_update();   // antes de readback

// Readback a CPU
fn::gfx::ssbo_readback(hist, 0, M*sizeof(uint), host_hist);
```

## Que barrier elegir

| Despues del compute, vas a... | Barrier |
|---|---|
| Otro compute que lee los SSBOs escritos | `barrier_storage()` |
| Renderizar leyendo uniforms | `barrier_uniform()` |
| Render que muestrea image2D escrito por compute | `barrier_image()` |
| Llamar `ssbo_readback` o usar como vertex buffer | `barrier_buffer_update()` |
| Estas debugeando y no sabes que paso | `barrier_all()` |

## Notas

- El `local_size_*` del wrapper DEBE coincidir con el del shader. Mantener ambos en una constante `kLocalSize` evita drift.
- Si `num_invocations` no es multiplo de `local_size_x`, el shader debe hacer guard `if (i >= u_count) return;` para no procesar hilos sobrantes.
- Limites tipicos en RTX 3070: `GL_MAX_COMPUTE_WORK_GROUP_COUNT` = 2^31-1 por dim, `GL_MAX_COMPUTE_WORK_GROUP_INVOCATIONS` = 1024 (= local_x*local_y*local_z max).