---
name: gpu_histogram_2d
kind: function
lang: cpp
domain: gfx
version: "1.0.0"
purity: impure
signature: "GpuHistogram2D gpu_histogram_2d_create(int nx, int ny); void gpu_histogram_2d_clear(GpuHistogram2D&); void gpu_histogram_2d_accumulate(GpuHistogram2D&, const Ssbo& samples_xy, int count, float xmin, float xmax, float ymin, float ymax); void gpu_histogram_2d_readback(const GpuHistogram2D&, unsigned int* out); void gpu_histogram_2d_to_density(const unsigned int* counts, int nx, int ny, float* out); void gpu_histogram_2d_destroy(GpuHistogram2D&)"
description: "Binner GPU 2D: SSBO float[2*N] xy-interleaved -> SSBO uint[nx*ny] row-major via atomicAdd. Output normalizable a float[] para alimentar heatmap_cpp_viz / contour_cpp_viz."
tags: [opengl, compute, histogram, atomic, gpu, gfx, heatmap, montecarlo]
uses_functions: ["gl_loader_cpp_gfx", "gpu_ssbo_cpp_gfx", "gpu_compute_program_cpp_gfx", "gpu_dispatch_cpp_gfx"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [GL/gl.h, GL/glext.h, vector]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/gfx/gpu_histogram_2d.cpp"
framework: opengl
params:
  - name: nx
    desc: "Bins en X."
  - name: ny
    desc: "Bins en Y."
  - name: samples_xy
    desc: "Ssbo float[2*count] xy-interleaved (x0, y0, x1, y1, ...). Binding 0 dentro del shader."
  - name: count
    desc: "Numero de pares xy a procesar."
  - name: xmin
    desc: "Limite inferior X. Samples con x fuera se descartan."
  - name: xmax
    desc: "Limite superior X."
  - name: ymin
    desc: "Limite inferior Y."
  - name: ymax
    desc: "Limite superior Y."
  - name: counts
    desc: "(to_density) Buffer leido de readback con uint[nx*ny] counts row-major."
  - name: out_density
    desc: "(to_density) Buffer destino float[nx*ny] normalizado a max=1.0. Si todos los counts son 0, se rellena con 0."
output: "Bins acumulados como uint[nx*ny] row-major (idx = y*nx + x). to_density convierte a float normalizado in-place. accumulate emite barrier_storage; readback emite barrier_buffer_update."
---

# gpu_histogram_2d

Binner 2D para densidades de muestras (joint posteriors, walk traces, scatter density). Output listo para `heatmap_cpp_viz` (z[]), `contour_cpp_viz` (z[] con marching squares) y `surface_plot_3d_cpp_viz`.

## Patron tipico (mcmc_full / mcmc_visualizer)

```cpp
auto h2d = fn::gfx::gpu_histogram_2d_create(128, 128);

// Cada step del MCMC genera un sample (x, y); los acumulamos en xy_ssbo
// como float[2*N]. Tras N steps:
fn::gfx::gpu_histogram_2d_clear(h2d);
fn::gfx::gpu_histogram_2d_accumulate(h2d, xy_ssbo, N,
                                     -5.0f, 5.0f, -5.0f, 5.0f);

std::vector<unsigned int> counts(128 * 128);
fn::gfx::gpu_histogram_2d_readback(h2d, counts.data());

std::vector<float> density(128 * 128);
fn::gfx::gpu_histogram_2d_to_density(counts.data(), 128, 128, density.data());

fn::viz::heatmap(density.data(), 128, 128, /*...*/);

fn::gfx::gpu_histogram_2d_destroy(h2d);
```

## Layout del SSBO de samples

`samples_xy` es `float[2*count]` interleaved. Si tu kernel MC produce `vec2` en std430 (8 bytes alineados), la lectura es la misma — el shader interpreta los pares como xy. Si usas un struct con padding, compactalo antes.

## Performance

Para 10^7 samples en grid 256×256 sobre RTX 3070: ~5-7 ms (memory-bound, 256k bins distribuidos), suficiente para refresh continuo a 60 FPS.

## Notas

- `to_density` es CPU-side y conserva resolucion fp32 sobre el max — adecuado para heatmaps. Para cdf/cumulative usar otra funcion (no incluida aqui).
- El binner mantiene el estado GL (programa + SSBO). Crear uno por viewport; no es seguro compartirlo entre threads del lado CPU.