raisin::texture

namespace

Free-function texture creators decoupled from RayraiWindow.

The same loaders are also reachable as static methods on RayraiWindow for historical reasons (RayraiWindow::loadHdrEquirectangularCubemap, etc.). Prefer the raisin::texture:: form in new code — it makes clear that the call is a stateless GL utility, not a scene-mutating operation, and keeps RayraiWindow's instance-method autocomplete uncluttered.

All functions require a current OpenGL context.

Functions

loadTextureWithTiling

#include <rayrai/Texture.hpp>

unsigned int loadTextureWithTiling(
    const char *path,
    bool useSrgbFormat=false)

Load an image file into an OpenGL texture with repeat tiling.

Parameters

Parameter	Description
path	Path to an image file supported by stb_image.
useSrgbFormat	If true, RGB/RGBA textures are uploaded as sRGB color textures. Use true for albedo/emissive color maps and false for data maps such as normal, metallic-roughness, AO, depth, and masks.

Returns OpenGL texture id, or 0 on failure.

The texture gets GL_REPEAT wrapping, mipmaps, and the process-wide defaults from setDefaultTextureFilteringQuality(). Results are cached per thread and per GL context by (path, sRGB flag), so repeated calls return the same id; a failed load is cached as 0 too. Requires a current GL context.

loadColorTextureWithTiling

#include <rayrai/Texture.hpp>

unsigned int loadColorTextureWithTiling(const char *path)

Load an albedo/emissive color texture as sRGB.

Parameters

Parameter	Description
path	Path to an image file supported by stb_image.

Returns OpenGL texture id, or 0 on failure.

loadDataTextureWithTiling

#include <rayrai/Texture.hpp>

unsigned int loadDataTextureWithTiling(const char *path)

Load a data texture as linear values.

Parameters

Parameter	Description
path	Path to an image file supported by stb_image.

Returns OpenGL texture id, or 0 on failure.

updateSingleChannelTexture

#include <rayrai/Texture.hpp>

unsigned int updateSingleChannelTexture(
    unsigned int existingTextureId,
    int width,
    int height,
    const unsigned char *data)

Create or update a single-channel R8 2D texture from raw pixel data.

Used for terrain splat control maps. Pass existingTextureId 0 to allocate a new texture, otherwise the existing texture is updated in place (and reallocated if the dimensions differ). New textures use linear filtering and clamp-to-edge wrapping. Requires a current GL context.

Parameters

Parameter	Description
existingTextureId	Texture to update, or 0 (or a deleted id) to create one.
width	Width in pixels; must be positive.
height	Height in pixels; must be positive.
data	width * height tightly packed bytes; must not be null.

Returns The texture id (new or reused), or 0 on invalid input.

loadHdrEquirectangularCubemap

#include <rayrai/Texture.hpp>

unsigned int loadHdrEquirectangularCubemap(
    const char *path,
    int faceSize=128,
    bool generateMipmaps=true)

Load a Radiance .hdr equirectangular environment into a cubemap texture.

This is intended for High/Ultra viewer PBR workflows. It does not allocate anything unless the application explicitly calls it.

Parameters

Parameter	Description
path	Path to a .hdr image supported by stb_image.
faceSize	Cubemap face size in pixels.
generateMipmaps	Whether to generate mip levels for roughness sampling.

Returns OpenGL cubemap id, or 0 on failure.

createHdrIrradianceCubemap

#include <rayrai/Texture.hpp>

unsigned int createHdrIrradianceCubemap(
    const char *path,
    int faceSize=32,
    int sampleCount=256)

Generate a diffuse irradiance cubemap from a Radiance .hdr equirectangular environment.

This is CPU-side cosine-hemisphere integration intended for High/Ultra PBR setup. Creation is explicit so Fast/Balanced RL rendering does not pay the cost.

Parameters

Parameter	Description
path	Path to a .hdr image supported by stb_image.
faceSize	Irradiance cubemap face size in pixels.
sampleCount	Number of hemisphere samples per texel.

Returns OpenGL cubemap id, or 0 on failure.

createHdrPrefilteredEnvironmentCubemap

#include <rayrai/Texture.hpp>

unsigned int createHdrPrefilteredEnvironmentCubemap(
    const char *path,
    int faceSize=128,
    int mipLevels=5,
    int sampleCount=256)

Generate a prefiltered specular environment cubemap from a Radiance .hdr equirectangular environment.

Mip level 0 is sharp and higher mip levels are GGX-prefiltered with increasing roughness. Use this as Material::prefilteredEnvironmentMap together with createSplitSumBrdfLut().

Parameters

Parameter	Description
path	Path to a .hdr image supported by stb_image.
faceSize	Base cubemap face size in pixels.
mipLevels	Number of mip levels to allocate and integrate.
sampleCount	Number of GGX samples per texel.

Returns OpenGL cubemap id, or 0 on failure.

createSplitSumBrdfLut

#include <rayrai/Texture.hpp>

unsigned int createSplitSumBrdfLut(int size=256, int sampleCount=512)

Create a numerically integrated split-sum BRDF LUT.

Use this as Material::brdfLut for High/Ultra PBR. Creation is explicit so Fast/Balance paths do not pay for it. The result is an RG16F texture (x = N.V, y = roughness).

Parameters

Parameter	Description
size	LUT width and height in texels.
sampleCount	GGX samples per texel.

Returns OpenGL texture id owned by the caller, or 0 if either argument is not positive.

setTextureAnisotropy

#include <rayrai/Texture.hpp>

void setTextureAnisotropy(
    unsigned int target,
    unsigned int textureId,
    float requestedLevel)

Apply anisotropic filtering to an existing 2D or cubemap texture if supported.

Parameters

Parameter	Description
target	Texture target such as GL_TEXTURE_2D or GL_TEXTURE_CUBE_MAP.
textureId	OpenGL texture id.
requestedLevel	Requested anisotropy level. Values <= 1 leave the texture unchanged.

setTextureFilteringQuality

#include <rayrai/Texture.hpp>

void setTextureFilteringQuality(
    unsigned int target,
    unsigned int textureId,
    float anisotropy,
    float mipLodBias)

Apply minification quality controls to an existing texture.

Positive mip LOD bias prefers blurrier mips and reduces distant texture shimmer. Negative values sharpen but can alias, so RayRai clamps the bias to [-1, 2].

Parameters

Parameter	Description
target	Texture target such as GL_TEXTURE_2D.
textureId	OpenGL texture id; 0 is ignored.
anisotropy	Requested anisotropy, see setTextureAnisotropy().
mipLodBias	Mip LOD bias, clamped to [-1, 2].

setDefaultTextureFilteringQuality

#include <rayrai/Texture.hpp>

void setDefaultTextureFilteringQuality(float anisotropy, float mipLodBias)

Set process-wide filtering defaults used by future loadTextureWithTiling() calls.

Parameters

Parameter	Description
anisotropy	Default anisotropy, clamped to [1, 16].
mipLodBias	Default mip LOD bias, clamped to [-1, 2].

getDefaultTextureFilteringQuality

#include <rayrai/Texture.hpp>

void getDefaultTextureFilteringQuality(float &anisotropy, float &mipLodBias)

Read process-wide filtering defaults used by future loadTextureWithTiling() calls.

Parameters

Parameter	Description
anisotropy (out)	Default anisotropy.
mipLodBias (out)	Default mip LOD bias.

setTextureSamplerState

#include <rayrai/Texture.hpp>

void setTextureSamplerState(
    unsigned int target,
    unsigned int textureId,
    int wrapS,
    int wrapT,
    int minFilter,
    int magFilter)

Apply sampler wrap/filter state to an existing texture.

Parameters

Parameter	Description
target	Texture target such as GL_TEXTURE_2D.
textureId	OpenGL texture id; 0 is ignored.
wrapS	GL wrap mode for S (e.g. GL_REPEAT).
wrapT	GL wrap mode for T.
minFilter	GL minification filter.
magFilter	GL magnification filter.