nvtt: nvtt::CubeSurface Struct Reference

nvtt

Loading...
Searching...
No Matches
Public Member Functions | Public Attributes | List of all members
nvtt::CubeSurface Struct Reference

A CubeSurface is one level of a cube map texture. More...

`#include <nvtt.h>`

## Public Member Functions

NVTT_API | CubeSurface ()
| Creates a null CubeSurface.
NVTT_API | CubeSurface (const CubeSurface &img)
| Copy constructor.
NVTT_API | ~CubeSurface ()
| Destructor.
NVTT_API void | operator= (const CubeSurface &img)
| Assignment operator.
NVTT_API bool | isNull () const
| Returns if this CubeSurface is null (i.e. has no underlying data, or all faces have size 0x0).
NVTT_API int | edgeLength () const
| Returns the edge length of any of the faces.
NVTT_API int | countMipmaps () const
| Returns the number of mips that would be in a full mipmap chain starting with this CubeSurface.
NVTT_API bool | load (const char *fileName, int mipmap)
| Load a cube map from a DDS file.
NVTT_API bool | loadFromMemory (const void *data, unsigned long long sizeInBytes, int mipmap)
| Load a cube map from a DDS file in memory.
NVTT_API bool | save (const char *fileName) const
| Save a cube map to a DDS file in memory.
NVTT_API Surface & | face (int face)
| Get a non-const reference to the surface for the given face.
NVTT_API const Surface & | face (int face) const
| Get a const reference to the surface for the given face.
NVTT_API void | fold (const Surface &img, CubeLayout layout)
| Sets this CubeSurface from a 2D unfolded surface in `img`.
NVTT_API Surface | unfold (CubeLayout layout) const
| Creates a Surface containing an unfolded/flattened representation of the cube surface.
NVTT_API float | average (int channel) const
| Computes an average value for the given channel over the entire sphere.
NVTT_API void | range (int channel, float *minimum_ptr, float *maximum_ptr) const
| Sets `*minimum_ptr` and `*maximum_ptr` to the minimum and maximum values in the given channel.
NVTT_API void | clamp (int channel, float low=0.0f, float high=1.0f)
| Clamps values in the given channel to the range [low, high].
NVTT_API CubeSurface | irradianceFilter (int size, EdgeFixup fixupMethod) const
| Unimplemented; returns a null CubeSurface.
NVTT_API CubeSurface | cosinePowerFilter (int size, float cosinePower, EdgeFixup fixupMethod) const
| Spherically convolves this CubeSurface with a `max(0.0f, cos(theta))^cosinePower` kernel, returning a CubeSurface with faces with dimension size x size.
NVTT_API CubeSurface | fastResample (int size, EdgeFixup fixupMethod) const
| Produces a resized version of this CubeSurface using nearest-neighbor sampling.
NVTT_API void | toLinear (float gamma)
| Raises channels 0...2 to the power `gamma`.
NVTT_API void | toGamma (float gamma)
| Raises channels 0...2 to the power `1/gamma`.
void | detach ()

## Public Attributes

Private * | m

## Detailed Description

A CubeSurface is one level of a cube map texture.

CubeSurfaces are either null, or contain six square Surfaces numbered 0 through 5, all with the same size (referred to as the edge length). By convention, these are the +x, -x, +y, -y, +z, and -z faces, in that order, of a cube map in a right-handed coordinate system.

These objects are reference-counted like nvtt::Surface.

Since
  NVTT 2.1

## Member Function Documentation

## ◆ average()

NVTT_API float nvtt::CubeSurface::average | ( | int | channel | ) | const

Computes an average value for the given channel over the entire sphere.

This takes solid angles into account when producing an average per steradian, so texels near face edges are weighted less than texels near face edges.

No gamma correction is performed, unlike nvtt::Surface::average().

## ◆ cosinePowerFilter()

NVTT_API CubeSurface nvtt::CubeSurface::cosinePowerFilter | ( | int | size,
|  | float | cosinePower,
|  | EdgeFixup | fixupMethod ) const

Spherically convolves this CubeSurface with a `max(0.0f, cos(theta))^cosinePower` kernel, returning a CubeSurface with faces with dimension size x size.

This is useful for generating prefiltered cube maps, as this corresponds to the cosine power used in the Phong reflection model (with energy conservation).

This handles how each cube map texel can have a different solid angle. It also only considers texels for which the value of the kernel (without normalization) is at least 0.001.

## ◆ countMipmaps()

NVTT_API int nvtt::CubeSurface::countMipmaps | ( |  | ) | const

Returns the number of mips that would be in a full mipmap chain starting with this CubeSurface.

For instance, a full mip chain for a cube map with 10x10 faces would consist of cube maps with sizes 10x10, 5x5, 2x2, and 1x1, and this function would return 4.

## ◆ face() [1/2]

NVTT_API Surface & nvtt::CubeSurface::face | ( | int | face | ) |

Get a non-const reference to the surface for the given face.

`face` must be in the range [0, 5].

## ◆ face() [2/2]

NVTT_API const Surface & nvtt::CubeSurface::face | ( | int | face | ) | const

Get a const reference to the surface for the given face.

`face` must be in the range [0, 5].

## ◆ fold()

NVTT_API void nvtt::CubeSurface::fold | ( | const Surface & | img,
|  | CubeLayout | layout )

Sets this CubeSurface from a 2D unfolded surface in `img`.

See also
  CubeLayout for allowed folding layouts.

## ◆ load()

NVTT_API bool nvtt::CubeSurface::load | ( | const char * | fileName,
|  | int | mipmap )

Load a cube map from a DDS file.

Parameters

  fileName | Path to the file to load. This uses the same character encoding as the `filename` argument of `fopen()`.
  mipmap | The mip to read. If `mipmap` is negative, then this reads the `abs(mipmap)`'th smallest mipmap.

If the DDS file has multiple array elements, this always loads the first one.

Returns whether the operation succeeded (for instance, this can fail if the file does not exist or if the mipmap was out of range).

## ◆ loadFromMemory()

NVTT_API bool nvtt::CubeSurface::loadFromMemory | ( | const void * | data,
|  | unsigned long long | sizeInBytes,
|  | int | mipmap )

Load a cube map from a DDS file in memory.

Parameters

  data | Pointer to the start of the file's data in memory.
  sizeInBytes | Length of the file's data.
  mipmap | The mip to read. If `mipmap` is negative, then this reads the `abs(mipmap)`'th smallest mipmap.

If the DDS file has multiple array elements, this always loads the first one.

Returns whether the operation succeeded (for instance, this can fail if the file does not exist or if the mipmap was out of range).

## ◆ range()

NVTT_API void nvtt::CubeSurface::range | ( | int | channel,
|  | float * | minimum_ptr,
|  | float * | maximum_ptr ) const

Sets `*minimum_ptr` and `*maximum_ptr` to the minimum and maximum values in the given channel.

If all faces have size 0 x 0 (in which case the cube surface isNull()), this will set `*minimum_ptr` to `FLT_MAX` and `*maximum_ptr` to 0.0f.

## ◆ save()

NVTT_API bool nvtt::CubeSurface::save | ( | const char * | fileName | ) | const

Save a cube map to a DDS file in memory.

Unimplemented - iterate over faces and save them instead.

## ◆ toGamma()

NVTT_API void nvtt::CubeSurface::toGamma | ( | float | gamma | ) |

Raises channels 0...2 to the power `1/gamma`.

Using a `gamma` of 2.2 approximates linear-to-sRGB conversion.

See also
  nvtt::Surface::toGamma()

## ◆ toLinear()

NVTT_API void nvtt::CubeSurface::toLinear | ( | float | gamma | ) |

Raises channels 0...2 to the power `gamma`.

Using a `gamma` of 2.2 approximates sRGB-to-linear conversion.

See also
  nvtt::Surface::toLinear()

## ◆ unfold()

NVTT_API Surface nvtt::CubeSurface::unfold | ( | CubeLayout | layout | ) | const

Creates a Surface containing an unfolded/flattened representation of the cube surface.

See also
  CubeLayout for allowed folding layouts.

The documentation for this struct was generated from the following file:

- nvtt/nvtt.h