esp::gfx::CubeMap class
#include <esp/gfx/CubeMap.h>

Public types

enum class TextureType: uint8_t { Color, Depth, ObjectId, Count }
enum (anonymous): Magnum::UnsignedInt { ColorOutput = Magnum::Shaders::GenericGL3D::ColorOutput, ObjectIdOutput = Magnum::Shaders::GenericGL3D::ObjectIdOutput }
enum class Flag: Magnum::UnsignedShort { ColorTexture = 1 << 0, DepthTexture = 1 << 1, ObjectIdTexture = 1 << 2, AutoBuildMipmap = 1 << 3, ManuallyBuildMipmap = 1 << 4 }
using Flags = Corrade::Containers::EnumSet<Flag>
Flags.

Constructors, destructors, conversion operators

CubeMap(int imageSize, Flags flags = Flags{Flag::ColorTexture}) explicit
, Constructor

Public functions

auto reset(int imageSize) -> bool
, reset the image size
auto getTexture(TextureType type) -> Magnum::GL::CubeMapTexture&
Get the cubemap texture based on the texture type.
auto getCubeMapSize() const -> int
get cube map size
auto saveTexture(TextureType type, const std::string& imageFilePrefix, unsigned int mipLevel = 0) -> bool
save the cubemap texture based on the texture type
void loadTexture(TextureType type, const std::string& imageFilePrefix, const std::string& imageFileExtension)
load cubemap texture from external images
void renderToTexture(CubeMapCamera& camera, scene::SceneGraph& sceneGraph, const char* drawableGroupName = "", RenderCamera::Flags flags = { RenderCamera::Flag::FrustumCulling|RenderCamera::Flag::ClearColor|RenderCamera::Flag::ClearDepth})
Render to cubemap texture using the camera.
void copySubImage(unsigned int cubeSideIndex, TextureType type, Magnum::GL::Texture2D& texture, unsigned int mipLevel = 0)
copy the texture from a specified cube face to a given texture (GPU->GPU) NOTE: can only call this function for the textures attaching to the color attachments
void prepareToDraw(unsigned int cubeSideIndex, RenderCamera::Flags flags = {RenderCamera::Flag::FrustumCulling|RenderCamera::Flag::ClearColor|RenderCamera::Flag::ClearDepth}, unsigned int mipLevel = 0)
Prepare to draw to the texture. It will bind the framebuffer, clear color, depth etc.
auto getMipmapLevels() const -> unsigned int
Get the mipmap levels NOTE: returns 1 if this is non-colored cubemap, or it is colored cubemap but without mipmap enabled.
void generateMipmap(TextureType type)
generate mipmap
auto getFlags() -> Flags
get flags

Enum documentation

enum class esp::gfx::CubeMap::TextureType: uint8_t

Enumerators
Color

rgba texture with 8 bits per channel
Depth

HDR depth texture
ObjectId

object id (uint) texture
Count

enum esp::gfx::CubeMap::(anonymous): Magnum::UnsignedInt

Enumerators
ColorOutput

Color shader output. Generic output, present always. Expects three- or four-component floating-point or normalized buffer attachment.
ObjectIdOutput

Object ID shader output. Generic output, present only if Flag::ObjectId is set. Expects a single-component unsigned integral attachment. Writes the value set in setObjectId() there.

enum class esp::gfx::CubeMap::Flag: Magnum::UnsignedShort

Enumerators
ColorTexture

create color cubemap
DepthTexture

create depth cubemap
ObjectIdTexture

create ObjectId cubemap
AutoBuildMipmap

Build mipmap for cubemap color texture By default, NO mipmap will be built, only 1 level (mip 0) By turning on this option, it will AUTOMATICALLY build the mipmap for the color texture if any (for example, after rendering to texture (mip 0), or loading the texture to mip 0.)
ManuallyBuildMipmap

Reserve the space for the mipmaps of the cubemap color texture. System will NOT automatically build the mipmaps for the user. By default, NO mipmap will be built, only 1 level (mip 0). By turning on this option, it will allocates the space for the mipmaps, but will not fillin the contents. This is useful e.g., in PBR prefiltered environment map computation.

Function documentation

esp::gfx::CubeMap::CubeMap(int imageSize, Flags flags = Flags{Flag::ColorTexture}) explicit

, Constructor

Parameters
imageSize the size of the cubemap texture (each face is size x size)
flags

bool esp::gfx::CubeMap::reset(int imageSize)

, reset the image size

Returns true, if image size has been changed, and reset has happened, otherwise false

Magnum::GL::CubeMapTexture& esp::gfx::CubeMap::getTexture(TextureType type)

Get the cubemap texture based on the texture type.

Returns Reference to the cubemap texture

bool esp::gfx::CubeMap::saveTexture(TextureType type, const std::string& imageFilePrefix, unsigned int mipLevel = 0)

save the cubemap texture based on the texture type

Parameters
type texture type
imageFilePrefix the filename prefix The 6 image files then would be: {imageFilePrefix}.{texType}.+X.png {imageFilePrefix}.{texType}.-X.png {imageFilePrefix}.{texType}.+Y.png {imageFilePrefix}.{texType}.-Y.png {imageFilePrefix}.{texType}.+Z.png {imageFilePrefix}.{texType}.-Z.png
mipLevel
Returns true, if success, otherwise false 
          +----+
          | -Y |
+----+----+----+----+
| -Z | -X | +Z | +X |
+----+----+----+----+
          | +Y |
          +----+

NOTE: +Y is top NOTE: In this version, it will lose precision when depth texture is saved to the disk. This is because the pixel format for depth texture is R32F with 1 bit of sign, 23 bits of mantissa and 8 bits of exponent while the radiance HDR is 8 bits of mantissa and 8 bits of exponent. So when it is saved, only 8 bits is saved to the R channel (GB channels just repeat the R channel twice).

void esp::gfx::CubeMap::loadTexture(TextureType type, const std::string& imageFilePrefix, const std::string& imageFileExtension)

load cubemap texture from external images

Parameters
type can be "rgba", "depth", or "objectId" (TODO)
imageFilePrefix the prefix of the image filename
imageFileExtension the image filename extension (such as "png", "jpg")
Returns true if succeeded, otherwise false The 6 image files then would be: {imageFilePrefix}.{texType}.+X.{imageFileExtension} {imageFilePrefix}.{texType}.-X.{imageFileExtension} {imageFilePrefix}.{texType}.+Y.{imageFileExtension} {imageFilePrefix}.{texType}.-Y.{imageFileExtension} {imageFilePrefix}.{texType}.+Z.{imageFileExtension} {imageFilePrefix}.{texType}.-Z.{imageFileExtension} 
          +----+
          | -Y |
+----+----+----+----+
| -Z | -X | +Z | +X |
+----+----+----+----+
          | +Y |
          +----+

NOTE: +Y is top

void esp::gfx::CubeMap::renderToTexture(CubeMapCamera& camera, scene::SceneGraph& sceneGraph, const char* drawableGroupName = "", RenderCamera::Flags flags = { RenderCamera::Flag::FrustumCulling|RenderCamera::Flag::ClearColor|RenderCamera::Flag::ClearDepth})

Render to cubemap texture using the camera.

Parameters
camera a cubemap camera NOTE: It will NOT automatically generate the mipmap for the user
sceneGraph
drawableGroupName
flags

void esp::gfx::CubeMap::copySubImage(unsigned int cubeSideIndex, TextureType type, Magnum::GL::Texture2D& texture, unsigned int mipLevel = 0)

copy the texture from a specified cube face to a given texture (GPU->GPU) NOTE: can only call this function for the textures attaching to the color attachments

Parameters
cubeSideIndex in index of the cube side, can be 0, 1, ..., 5
type in texture type NOTE: the type CANNOT be the depth texture
texture in/out 2D target texture
mipLevel in mipmap level

void esp::gfx::CubeMap::prepareToDraw(unsigned int cubeSideIndex, RenderCamera::Flags flags = {RenderCamera::Flag::FrustumCulling|RenderCamera::Flag::ClearColor|RenderCamera::Flag::ClearDepth}, unsigned int mipLevel = 0)

Prepare to draw to the texture. It will bind the framebuffer, clear color, depth etc.

Parameters
cubeSideIndex in index of the cube side, can be 0, 1, 2, 3, 4, or 5
flags in flags to control the rendering
mipLevel in

mip level of the texture. default value is 0. This is an advanced feature. In most cases user do not have to set it. NOTE: If a non-zero miplevel is specified, it requires:

  • The cubemap is color texture; (does not make sense to talk about mip level for depth or object ids)
  • Flag::ManuallyBuildMipmap is set;
  • value is smaller than the max mip level, which is log2(mip0_size) + 1;