Texmap

---

A texture map contains the raw texel data that are ready to be uploaded to the GPU. Through this interface, you can change a variety of settings and properties; where each of them will have a direct impact on the texel data maintained by the structure.

The interface below also contains a series of helpers which allows you to directly access texel data, convert, resize and even save the raw data directly to disk using popular file formats etc...

See Also

Texture, Sampler

Static Variables

---

Name	Description
byte_array	Access the raw byte array of texel data.
Declaration unsigned char *byte_array Note Set to nil if the Texmap data is converted to floating point values (see the TexmapOptions fFloat).
float_array	Access the raw floating point array of texel data.
Declaration float *float_array Note Set to nil if the Texmap data is not converted to floating point values.

Variables

---

Name	Description
width	Width of the texture data in pixel.
Declaration unsigned short width
height	Height of the texture data in pixel.
Declaration unsigned short height
depth	Depth of the texture data in pixel.
Declaration unsigned short depth
byte	Amount of components per pixel.
Declaration unsigned char byte Byte Type Description 1 Luminance or Alpha Either grayscale or alpha channel. 2 Luminance+Alpha Grayscale and alpha channel. 3 RGB Conventional red,green,blue component. 4 RGBA Conventional RGB with an alpha channel. 5 Depth Depth only texmap data (3 bytes). 6 Depth+Stencil Depth and Stencil data (3 bytes + 1 byte). 7 KTX Either ETC2 or ASTC compression format; variable size based on the format used.
samples	Amount of samples for multisample anti-alias Texture.
Declaration unsigned char samples Remarks The default value when none is specified is 4.
options	Bit mask of TexmapOptions flag(s) currently assigned to the active Texmap.
Declaration int options Cap Value Description fLuminanceToAlpha bit.lshift(1,0) Convert luminance to alpha. f16bits bit.lshift(1,1) Specifies that the Texmap data is 16 bits. fUse5551 bit.lshift(1,2) Force 16bits RGBA texture to be converted as 5551 instead of 4444. fFloat bit.lshift(1,3) Force the Texmap data to use floating points for each component. fNoClear bit.lshift(1,4) Flag to prevent the Texmap data to be freed upong successfull GPU upload. fNoSave bit.lshift(1,5) Flag to prevent the Texmap data to be saved. fNoOverride bit.lshift(1,6) Flag to prevent the Texmap to be resized or compressed. fMultiSample bit.lshift(1,7) Specify that the Texmap Texture attachment is of the type multisample. fArray bit.lshift(1,8) Specify that the depth value of Texmap should be used as an array and not a texture 3d. f11bits bit.lshift(1,9) Allows a floating point texture to be of the type R11G11B10.

Functions

---

Name	Description
To16Bits	Convert the current Texmap data to 16bits.
Declaration bool To16Bits( void ) Return Value true if the operation is successfull; false if one of the failure case below occur: The byte size if greater than 4; depth or depth+stencil texmap cannot be converted (as well as KTX). No texel array is available (byte_array is equal to nil). The depth of the Texmap is greater than 1 (3D texture of 2D array textures are not supported). The f16bits flags is not set as a texmap options. The Texmap is using floating points value for each component (fFloat).
Generate	Regenerate the Texmap texel array.
Declaration void Generate( const bool blank ) Parameters blank: Force the texel array to be filled with zeros. Remarks Each time either the width, height, byte or depth value are changed this function must be called to resize the array.
Resize	Upscale or downscale the current texel data to a new resolution.
Declaration bool Resize( const unsigned short new_width, const unsigned short new_height, unsigned char filter ) Parameters new_width: The new width of the texel data. new_height: The new height of the texel data. filter: The type of filter to apply when upsampling or downsampling the Texmap. Filters STBIR_FILTER_DEFAULT = 0, // Default upscaling or downscaling filter. STBIR_FILTER_BOX = 1, // A trapezoid w/1-pixel wide ramps, same result as box for integer scale ratios. STBIR_FILTER_TRIANGLE = 2, // On upsampling, produces same results as bilinear texture filtering. STBIR_FILTER_CUBICBSPLINE = 3, // The cubic b-spline (aka Mitchell-Netrevalli with B=1,C=0), gaussian-esque. STBIR_FILTER_CATMULLROM = 4, // An interpolating cubic spline. STBIR_FILTER_MITCHELL = 5, // Mitchell-Netrevalli filter with B=1/3, C=1/3. Value Filter Description 0 Default Default filter; Catmull Rom for upsampling and Mitchell for downsampling. 1 Box A trapezoid w/1-pixel wide ramps, which gives the same result as box for integer scale ratios. 2 Triangle On upsampling, produces same results as bilinear texture filtering. 3 Cubic Spline A cubic b-spline (aka Mitchell-Netrevalli with B=1,C=0). 4 Catmull Rom An interpolating cubic spline. 5 Mitchell Mitchell-Netrevalli filter with B=1/3, C=1/3. Return Value true if the operation is successfull; else return false if one of the fail condition occurs: No texel array is available (texel_array is equal to nil). The byte size if greater than 4; depth or depth+stencil texmap cannot be converted (as well as KTX). The depth of the Texmap is greater than 1 (3D texture or 2D array are not yet supported). The new width and height provided are the same as the current one. The Texmap is 16 bits encoded. The Texmap as note been marked to allow overrides (fOverride).
GetByteSize	Return the size of the current byte/options Texmap configuration.
Declaration unsigned char GetByteSize( void ) Return Value The byte size amount.
SetByte	Manually update the byte value of a texel.
Declaration bool SetByte( unsigned int index, unsigned char texel ) Parameters index: Index of the texel to update. texel: The new value of the texel. Return Value true if the texel value have been updated; false if the texel index is invalid or if the Texmap is using floating point.
SetFloat	Manually update the float value of a texel.
Declaration bool SetFloat( unsigned int index, float texel ) Parameters index: Index of the texel to update. texel: The new value of the texel. Return Value true if the texel value have been updated; false if the texel index is invalid or if the Texmap is using using bytes only (no floating point).
GetByte	Retrieve the current value of a specific byte texel.
Declaration unsigned char GetByte( unsigned int index ) Parameters index: Index of the texel to retrieve. Return Value 0 if the index provided is out of bounds or if the Texmap is using floating points or if no texel array is available; else return the value of the texel pointed by index.
GetFloat	Retrieve the current value of a specific floating point texel.
Declaration float GetFloat( unsigned int index ) Parameters index: Index of the texel to retrieve. Return Value 0.0 if the index provided is out of bounds or if the Texmap is using bytes only or if no texel array is available; else return the value of the texel pointed by index.
GetMemUsage	Total amount in bytes used by the Texmap texel data.
Declaration unsigned int GetMemUsage( void )
Clear	Release the current texel array data from memory.
Declaration void Clear( void )
SavePNG	Save on disk the current texel data array to PNG.
Declaration bool SavePNG( const char *filename ) Parameters filename: Where to save the PNG. Return Value true the file is written successfully; false if one of the condition below occur: No texel data is available. The Texmap byte value is greater than 4. The Texmap depth value is greater than 1. The Texmap texel data is converted to 16 bits. The Texmap texel data is converted to floating points.
SaveTGA	Save on disk the current texel data array to TGA.
Declaration bool SaveTGA( const char *filename ) Parameters filename: Where to save the TGA. Return Value true the file is written successfully; false if one of the condition below occur: No texel data is available. The Texmap byte value is greater than 4. The Texmap depth value is greater than 1. The Texmap texel data is converted to 16 bits. The Texmap texel data is converted to floating points.
SaveBMP	Save on disk the current texel data array to BMP.
Declaration bool SaveBMP( const char *filename ) Parameters filename: Where to save the BMP. Return Value true the file is written successfully; false if one of the condition below occur: No texel data is available. The Texmap byte value is greater than 4. The Texmap depth value is greater than 1. The Texmap texel data is converted to 16 bits. The Texmap texel data is converted to floating points.
SaveHDR	Save on disk the current texel data array to HDR.
Declaration bool SaveHDR( const char *filename ) Parameters filename: Where to save the HDR. Return Value true the file is written successfully; false if one of the condition below occur: No texel data is available. The Texmap byte value is greater than 4. The Texmap depth value is greater than 1. The Texmap texel data is converted to 16 bits. The Texmap texel data does not contain floating point values.
SaveKTX	Save on disk the current texel data array to KTX.
Declaration bool SaveKTX( const char *filename ) Parameters filename: Where to save the KTX. Return Value true the file is written successfully; false if one of the condition below occur: No texel data is available. The Texmap does not contain compressed data (either ETC2 or ASTC).

TexmapOptions

---

Bit flags are combined together to form the options used by a Texmap. The flags listed below will modify the type of data handled by the Texmap as well as some of its internal behaviors.

• fLuminanceToAlpha: Convert grayscale to an alpha channel.
• f16bits: Specifies that the Texmap data is converted to 16 bits.
• fUse5551: In the event, the Texmap contains an RGBA channel and is flagged to be converted as 16 bits; convert using the 5551 methods instead of using the default 4444 bits per component.
• fFloat: Flag the Texmap to use floating point values instead of bytes.
• fNoClear: Prevent the Texmap texel data to be freed after it is upload to the GPU.
• fNoSave: Force to do not save the texmap data. This option is generally use to mark texmaps that are procedurally generated at runtime and do not need to be saved.
• fNoOverride: Prevent the Texmap to be resized or compressed.
• fMultiSample: Enable multisample anti-alias. Take note that MSAA textures needs to be blit into a regular attachment. The code below show how to blit color and depth Texture attachment from one framebuffer to another.
• fArray: Convert a texture3D into a sampler2DArray.

Lua
function OnEnd()

    -- The destination framebuffer (the active camera).
    local dst = event.object.data.camera.framebuffer

    -- The source framebuffer.
    local src = event.object.scene:GetObject( "Camera" ).data.camera.framebuffer

    dst:BlitBegin()

    -- Blit the color and depth buffer.
    dst:Blit( src,
              Graphics.ClearBuffer.fColorBufferBit +
              Graphics.ClearBuffer.fDepthBufferBit,
              0,
              0,
              false) -- Requires linear to be set to false.

    dst:BlitEnd()
end