easy-gl › Texture

Texture

Manages a single OpenGL texture object. Non-copyable, movable, RAII.

Creating a 2D texture

easygl::Texture tex;
tex.create();
tex.bind(easygl::TextureTarget::Texture2D);

// Set filtering and wrap mode
tex.set_parameter(easygl::TextureTarget::Texture2D,
                   easygl::TextureParameter::MinFilter,
                   static_cast<int>(easygl::TextureMinFilter::LinearMipmapLinear));
tex.set_parameter(easygl::TextureTarget::Texture2D,
                   easygl::TextureParameter::MagFilter,
                   static_cast<int>(easygl::TextureMagFilter::Linear));
tex.set_parameter(easygl::TextureTarget::Texture2D,
                   easygl::TextureParameter::WrapS,
                   static_cast<int>(easygl::TextureWrapMode::Repeat));
tex.set_parameter(easygl::TextureTarget::Texture2D,
                   easygl::TextureParameter::WrapT,
                   static_cast<int>(easygl::TextureWrapMode::Repeat));

// Upload pixel data (RGBA8)
tex.set_image_2d(easygl::TextureTarget::Texture2D,
                  0,                               // mip level
                  easygl::InternalFormat::Rgba8,
                  width, height,
                  easygl::PixelFormat::Rgba,
                  easygl::PixelType::UnsignedByte,
                  pixelData);

tex.generate_mipmap(easygl::TextureTarget::Texture2D);

Immutable storage (recommended)

Use set_storage_2d to allocate immutable storage before uploading. This is more efficient and avoids resizing issues:

tex.create();
tex.bind(easygl::TextureTarget::Texture2D);
tex.set_storage_2d(easygl::TextureTarget::Texture2D,
                    4,                               // mip levels
                    easygl::InternalFormat::Rgba8,
                    512, 512);

tex.set_sub_image_2d(easygl::TextureTarget::Texture2D,
                      0, 0, 0, 512, 512,
                      easygl::PixelFormat::Rgba,
                      easygl::PixelType::UnsignedByte,
                      pixelData);
tex.generate_mipmap(easygl::TextureTarget::Texture2D);

Binding to a texture unit

// Activate unit and bind in one call:
tex.active_bind(easygl::TextureUnit::Texture0,
                easygl::TextureTarget::Texture2D);

// Tell the shader which unit to sample from:
prog.set_uniform(prog.uniform_location("uTex"), 0);

3D texture

easygl::Texture tex3d;
tex3d.create();
tex3d.bind(easygl::TextureTarget::Texture3D);
tex3d.set_storage_3d(easygl::TextureTarget::Texture3D,
                       1,
                       easygl::InternalFormat::R8,
                       64, 64, 64);
tex3d.set_sub_image_3d(easygl::TextureTarget::Texture3D,
                         0, 0, 0, 0, 64, 64, 64,
                         easygl::PixelFormat::Red,
                         easygl::PixelType::UnsignedByte,
                         volumeData);

Multisampled texture

easygl::Texture ms;
ms.create();
ms.bind(easygl::TextureTarget::Texture2DMultisample);
ms.set_storage_2d_multisample(
    easygl::TextureTarget::Texture2DMultisample,
    4,                                       // 4x MSAA
    easygl::InternalFormat::Rgba8,
    width, height,
    true);                                   // fixed sample locations

Image unit (compute shaders)

tex.bind_image(
    0,                                   // image unit
    0,                                   // mip level
    false,                               // not layered
    0,                                   // layer (ignored)
    easygl::ImageAccess::WriteOnly,
    easygl::InternalFormat::Rgba8);

Common InternalFormat values

Format	Channels	Bits/channel
`InternalFormat::R8`	1 (red)	8 unorm
`InternalFormat::Rg8`	2	8 unorm
`InternalFormat::Rgb8`	3	8 unorm
`InternalFormat::Rgba8`	4	8 unorm
`InternalFormat::Rgba16f`	4	16 float
`InternalFormat::Rgba32f`	4	32 float
`InternalFormat::DepthComponent24`	depth	24
`InternalFormat::DepthStencil`	depth+stencil	24+8
`InternalFormat::Srgb8Alpha8`	4 sRGB	8

Method reference

Method	Description
`create()`	Allocate GL texture handle.
`destroy()`	Free handle. Noexcept.
`bind(target)`	Bind texture to target on the active unit.
`active_bind(unit, target)`	Activate unit and bind.
`set_parameter(target, pname, int/float)`	Set a texture parameter.
`set_image_2d(...)`	Upload 2D image data (mutable storage).
`set_image_3d(...)`	Upload 3D image data.
`set_sub_image_2d(...)`	Update a 2D subregion.
`set_sub_image_3d(...)`	Update a 3D subregion.
`set_storage_2d(...)`	Allocate immutable 2D storage.
`set_storage_3d(...)`	Allocate immutable 3D storage.
`set_storage_2d_multisample(...)`	Allocate immutable MSAA 2D storage.
`set_compressed_image_2d(...)`	Upload compressed 2D data (DXT/BC/etc.).
`set_compressed_image_3d(...)`	Upload compressed 3D data.
`generate_mipmap(target)`	Auto-generate full mip chain.
`bind_image(unit, level, layered, layer, access, format)`	Bind for image load/store (compute).
`is_created()`	True if handle is allocated.
`native_handle()`	Raw GL integer ID.
`reset_handle_no_gl()`	Context-loss recovery.