fn_registry/cpp/functions/gfx/gpu_histogram_2d.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, tested, tests, test_file_path, file_path, framework, params, output

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	tested	tests	test_file_path	file_path	framework	params	output
gpu_histogram_2d	function	cpp	gfx	1.0.0	impure	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&)	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.	opengl compute histogram atomic gpu gfx heatmap montecarlo pendiente-usar	gl_loader_cpp_gfx gpu_ssbo_cpp_gfx gpu_compute_program_cpp_gfx gpu_dispatch_cpp_gfx			false	error_go_core	GL/gl.h GL/glext.h vector	false			cpp/functions/gfx/gpu_histogram_2d.cpp	opengl	name desc nx Bins en X. name desc ny Bins en Y. name desc samples_xy Ssbo float[2*count] xy-interleaved (x0, y0, x1, y1, ...). Binding 0 dentro del shader. name desc count Numero de pares xy a procesar. name desc xmin Limite inferior X. Samples con x fuera se descartan. name desc xmax Limite superior X. name desc ymin Limite inferior Y. name desc ymax Limite superior Y. name desc counts (to_density) Buffer leido de readback con uint[nx*ny] counts row-major. name desc out_density (to_density) Buffer destino float[nx*ny] normalizado a max=1.0. Si todos los counts son 0, se rellena con 0.	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)

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.