---
name: gl_texture_load
kind: function
lang: cpp
domain: gfx
version: "1.0.0"
purity: impure
signature: "GlTexture gl_texture_load(const char* path, bool flip_y, bool srgb)"
description: "Carga PNG/JPG/BMP/TGA/HDR desde disco (o memoria) a una textura OpenGL lista para usar como sampler2D. Vendorea stb_image. Soporta sRGB (GL_SRGB8_ALPHA8) y HDR (GL_RGBA16F via stbi_loadf). Genera mipmaps automaticamente. flip_y=true por defecto coincide con la convencion UV de OpenGL."
tags: [opengl, texture, image, png, jpg, hdr, stb_image, gfx]
uses_functions: ["gl_loader_cpp_gfx"]
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [stb_image.h, GL/gl.h, GL/glext.h]
tested: false
tests: []
test_file_path: ""
file_path: "cpp/functions/gfx/gl_texture_load.cpp"
framework: opengl
params:
  - name: path
    desc: "Ruta al archivo de imagen (PNG/JPG/BMP/TGA o .hdr para float). UTF-8."
  - name: flip_y
    desc: "Si es true, voltea verticalmente al cargar (convencion OpenGL: V hacia arriba). Default true."
  - name: srgb
    desc: "Si es true, sube como GL_SRGB8_ALPHA8 (gamma correcto sin pow(c, 2.2) en shader). Solo aplica a LDR. Default false."
output: "GlTexture con id=GLuint listo para glBindTexture, w/h/channels de la imagen original. Si falla, id=0 y ok()==false; usar gl_texture_last_error() para detalle."
---

# gl_texture_load

Funcion impura del registry C++ que carga una imagen desde disco (o memoria) y devuelve una textura OpenGL lista para samplear desde un shader. Vendorea [stb_image](https://github.com/nothings/stb) en `cpp/vendor/stb/`.

## API

```cpp
namespace fn {

struct GlTexture {
    GLuint id = 0;
    int    w  = 0;
    int    h  = 0;
    int    channels = 0;
    bool   ok() const { return id != 0; }
};

GlTexture gl_texture_load(const char* path, bool flip_y = true, bool srgb = false);
GlTexture gl_texture_load_from_memory(const unsigned char* data, int size,
                                      bool flip_y = true, bool srgb = false);

void gl_texture_destroy(GlTexture& tex);
const char* gl_texture_last_error();
void gl_texture_bind_uniform(GLuint program, const char* name,
                             const GlTexture& tex, int unit);

} // namespace fn
```

## Uso

```cpp
#include "gfx/gl_texture_load.h"

auto tex = fn::gl_texture_load("assets/noise.png");
if (!tex.ok()) {
    std::fprintf(stderr, "error: %s\n", fn::gl_texture_last_error());
    return 1;
}

glUseProgram(prog);
fn::gl_texture_bind_uniform(prog, "u_noise", tex, /*unit=*/0);
glDrawArrays(GL_TRIANGLES, 0, 6);

// al destruir:
fn::gl_texture_destroy(tex);
```

## Comportamiento

- Forzamos 4 canales (RGBA) al decodificar via stb (`req_comp=4`), asi el upload a `glTexImage2D` siempre es regular.
- Filtros: `GL_LINEAR_MIPMAP_LINEAR` (min) + `GL_LINEAR` (mag). Mipmaps generados con `glGenerateMipmap`.
- Wrap: `GL_REPEAT` en S y T.
- HDR (`.hdr`): `stbi_loadf` + `GL_RGBA16F` (driver con GL 3.0+). En este caso `srgb` se ignora.
- sRGB (LDR + `srgb=true`): internal format `GL_SRGB8_ALPHA8`. El driver convierte a linear automaticamente al samplear.
- `flip_y=true` por defecto — la mayoria de PNGs vienen con (0,0) arriba; OpenGL espera (0,0) abajo.

## Errores

- En fallo, `id == 0` y `ok() == false`. El detalle (string de stb o "glGenTextures returned 0") se guarda en un `thread_local` accesible via `gl_texture_last_error()` hasta el siguiente `gl_texture_load*` en el mismo thread.

## Limites

- Tamano practico: <= 8192 px por lado (depende del driver — `GL_MAX_TEXTURE_SIZE`).
- No reentrante con la misma stb-flag global: stb usa una variable global para `flip_vertically`. Si dos threads cargan en paralelo, el resultado puede mezclar los flags. Para paralelo serio, serializar las llamadas o usar `stbi__ldr_to_hdr` directo con flag local.

## Composicion

Depende de `gl_loader_cpp_gfx` para los simbolos `glActiveTexture`, `glGenerateMipmap`, `glUseProgram`, `glGetUniformLocation`, `glUniform1i` (en Linux son simbolos directos via `GL_GLEXT_PROTOTYPES`; en Windows se resuelven con `wglGetProcAddress`).

Compone naturalmente con:
- `gl_shader_cpp_gfx` — para usar la textura en un fragment shader (uniform sampler2D).
- `shader_canvas_cpp_gfx` — un canvas full-screen que samplea la textura con uniforms de tint/zoom.

## Atribucion

stb_image v2.30 — public domain (MIT-0). Ver `cpp/vendor/stb/README.md`.