nvtt: nvtt::Surface Struct Reference

nvtt

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

A surface is one level of a 2D or 3D texture. More...

`#include <nvtt.h>`

## Public Member Functions

NVTT_API | Surface ()
| Creates an empty surface. All data will be null until a setImage() function is called.
NVTT_API | Surface (const Surface &img)
| Copy constructor.
NVTT_API | ~Surface ()
| Destructor.
NVTT_API void | operator= (const Surface &img)
| Assignment operator.
NVTT_API Surface | clone () const
| Creates a deep copy of this Surface, with its own internal data. (New in NVTT 3.1)
NVTT_API void | setWrapMode (WrapMode mode)
| Set the Surface's wrap mode. See WrapMode for details.
NVTT_API void | setAlphaMode (AlphaMode alphaMode)
| Set the Surface's alpha mode. See AlphaMode for details.
NVTT_API void | setNormalMap (bool isNormalMap)
| Set whether the Surface represents a normal map. This can be accessed using isNormalMap(), and e.g. affects whether DDS files are written with the normal map flag.
NVTT_API bool | isNull () const
| Returns if the surface is null (i.e. refers to nothing, such as if it was just created using Surface()).
NVTT_API int | width () const
| Returns the width (X size) of the surface.
NVTT_API int | height () const
| Returns the height (Y size) of the surface.
NVTT_API int | depth () const
| Returns the depth (Z size) of the surface. 1 for 2D surfaces.
NVTT_API TextureType | type () const
| Returns the dimensionality of the surface. This is set for instance by setImage().
NVTT_API WrapMode | wrapMode () const
| Returns the wrap mode of the surface. See setWrapMode()
NVTT_API AlphaMode | alphaMode () const
| Returns the alpha mode of the surface. See setAlphaMode()
NVTT_API bool | isNormalMap () const
| Returns whether the image represents a normal map. See setNormalMap()
NVTT_API int | countMipmaps () const
| Returns the number of mipmaps in a full mipmap chain. Each mip is half the size of the previous, rounding down, until and including a 1x1 mip.
NVTT_API int | countMipmaps (int min_size) const
| Returns the number of mipmaps in a mipmap chain, stopping when canMakeNextMipmap() returns false.
NVTT_API float | alphaTestCoverage (float alphaRef=0.5, int alpha_channel=3) const
| Returns the approximate fraction (0 to 1) of the image with an alpha value greater than `alphaRef`.
NVTT_API float | average (int channel, int alpha_channel=-1, float gamma=2.2f) const
| Computes the average of a channel, possibly with alpha or with a gamma transfer function.
NVTT_API const float * | data () const
| Returns a `const` pointer to the surface's CPU data.
NVTT_API const float * | channel (int i) const
| Returns a `const` pointer to channel i's CPU data.
NVTT_API float * | data ()
| Returns a pointer that can be used to modify the surface's CPU data. See data() const.
NVTT_API float * | channel (int i)
| Returns a pointer that can be used to modify channel i's CPU data. See channel(int) const.
NVTT_API void | histogram (int channel, float rangeMin, float rangeMax, int binCount, int *binPtr, TimingContext *tc=0) const
| Stores a histogram of channel values between `rangeMin` and `rangeMax` into `binPtr[0...binCount-1]`.
NVTT_API void | range (int channel, float *rangeMin, float *rangeMax, int alpha_channel=-1, float alpha_ref=0.f, TimingContext *tc=0) const
| Sets `*rangeMin` and `*rangeMax` to the range of values in the channel, possibly using alpha testing.
NVTT_API bool | load (const char *fileName, bool *hasAlpha=0, bool expectSigned=false, TimingContext *tc=0)
| Loads texture data from a file.
NVTT_API bool | loadFromMemory (const void *data, unsigned long long sizeInBytes, bool *hasAlpha=0, bool expectSigned=false, TimingContext *tc=0)
| Variant of load() that reads from memory instead of a file.
NVTT_API bool | save (const char *fileName, bool hasAlpha=false, bool hdr=false, TimingContext *tc=0) const
| Saves texture data to file.
NVTT_API bool | setImage (int w, int h, int d, TimingContext *tc=0)
| Sets this surface to a new w x h x d uninitialized image.
NVTT_API bool | setImage (InputFormat format, int w, int h, int d, const void *data, bool unsignedToSigned=false, TimingContext *tc=0)
| Sets this surface given uncompressed input data.
NVTT_API bool | setImage (InputFormat format, int w, int h, int d, const void *r, const void *g, const void *b, const void *a, TimingContext *tc=0)
| Sets this surface given uncompressed input data, with different pointers for each channel.
NVTT_API bool | setImage2D (Format format, int w, int h, const void *data, TimingContext *tc=0)
| Set 2D surface values from an encoded data source. Same as setImage3D() with `d=1`.
NVTT_API bool | setImage3D (Format format, int w, int h, int d, const void *data, TimingContext *tc=0)
| Set surface values from an encoded data source.
NVTT_API void | resize (int w, int h, int d, ResizeFilter filter, TimingContext *tc=0)
| Resizes this surface to have size w x h x d using a given filter.
NVTT_API void | resize (int w, int h, int d, ResizeFilter filter, float filterWidth, const float *params=0, TimingContext *tc=0)
NVTT_API void | resize (int maxExtent, RoundMode mode, ResizeFilter filter, TimingContext *tc=0)
| Resizes this surface so that its largest side has length `maxExtent`, subject to a rounding mode.
NVTT_API void | resize (int maxExtent, RoundMode mode, ResizeFilter filter, float filterWidth, const float *params=0, TimingContext *tc=0)
| Resizes this surface so that its largest side has length `maxExtent`, subject to a rounding mode, using customizable filter parameters.
NVTT_API void | resize_make_square (int maxExtent, RoundMode roundMode, ResizeFilter filter, TimingContext *tc=0)
| Resizes this surface so that its longest side has length `maxExtent` and the result is square or cubical.
NVTT_API bool | buildNextMipmap (MipmapFilter filter, int min_size=1, TimingContext *tc=0)
| Resizes this surface to create the next mip in a mipmap chain.
NVTT_API bool | buildNextMipmap (MipmapFilter filter, float filterWidth, const float *params=0, int min_size=1, TimingContext *tc=0)
| Version of buildNextMipmap(MipmapFilter, int, TimingContext*) with customizable parameters.
NVTT_API bool | buildNextMipmapSolidColor (const float *const color_components, TimingContext *tc=0)
| Replaces this surface with a surface the size of the next mip in a mip chain (half the width and height), but with each channel cleared to a constant value.
NVTT_API void | canvasSize (int w, int h, int d, TimingContext *tc=0)
| Crops or expands this surface from the (0,0,0) corner, with any new values cleared to 0.
NVTT_API bool | canMakeNextMipmap (int min_size=1)
| Returns whether a the surface would have a next mip in a mip chain with minimum size `min_size.
NVTT_API void | toLinear (float gamma, TimingContext *tc=0)
| Raises channels 0...2 to the power `gamma`.
NVTT_API void | toGamma (float gamma, TimingContext *tc=0)
| Raises channels 0...2 to the power `1/gamma`.
NVTT_API void | toLinear (int channel, float gamma, TimingContext *tc=0)
| Raises the given channel to the power `gamma`.
NVTT_API void | toGamma (int channel, float gamma, TimingContext *tc=0)
| Raises the given channel to the power `1/gamma`.
NVTT_API void | toSrgb (TimingContext *tc=0)
| Applies the linear-to-sRGB transfer function to channels 0...2.
NVTT_API void | toSrgbUnclamped (TimingContext *tc=0)
| Applies the linear-to-sRGB transfer function to channels 0...2, but does not clamp output to [0,1].
NVTT_API void | toLinearFromSrgb (TimingContext *tc=0)
| Applies the sRGB-to-linear transfer function to channels 0...2.
NVTT_API void | toLinearFromSrgbUnclamped (TimingContext *tc=0)
| Applies the sRGB-to-linear transfer function to channels 0...2, but does not clamp output to [0,1].
NVTT_API void | toXenonSrgb (TimingContext *tc=0)
| Converts colors in channels 0...2 from linear to a piecewise linear sRGB approximation.
NVTT_API void | toLinearFromXenonSrgb (TimingContext *tc=0)
| Converts colors in channels 0...2 from the Xenon sRGB piecewise linear sRGB approximation to linear.
NVTT_API void | transform (const float w0[4], const float w1[4], const float w2[4], const float w3[4], const float offset[4], TimingContext *tc=0)
| Applies a 4x4 affine transformation to the values in channels 0...3.
NVTT_API void | swizzle (int r, int g, int b, int a, TimingContext *tc=0)
| Swizzles the channels of the surface.
NVTT_API void | scaleBias (int channel, float scale, float bias, TimingContext *tc=0)
| Applies a scale and bias to the given channel. Each value x is replaced by x * scale + bias.
NVTT_API void | clamp (int channel, float low=0.0f, float high=1.0f, TimingContext *tc=0)
| Clamps all values in the channel to the range [low, high].
NVTT_API void | blend (float r, float g, float b, float a, float t, TimingContext *tc=0)
| Interpolates all texels between their current color and a constant color `(r, g, b, a)`.
NVTT_API void | premultiplyAlpha (TimingContext *tc=0)
| Converts to premultiplied alpha, replacing `(r, g, b, a)` with `(ar, ag, ab, a)`.
NVTT_API void | demultiplyAlpha (float epsilon=1e-12f, TimingContext *tc=0)
| Converts from premultiplied to unpremultiplied alpha, with special handling around zero alpha values.
NVTT_API void | toGreyScale (float redScale, float greenScale, float blueScale, float alphaScale, TimingContext *tc=0)
| Sets channels 0...3 to the result of converting to grayscale, with customizable channel weights.
NVTT_API void | setBorder (float r, float g, float b, float a, TimingContext *tc=0)
| Sets all texels on the border of the surface to a solid color.
NVTT_API void | fill (float r, float g, float b, float a, TimingContext *tc=0)
| Sets all texels in the surface to a solid color.
NVTT_API void | scaleAlphaToCoverage (float coverage, float alphaRef=0.5f, int alpha_channel=3, TimingContext *tc=0)
| Attempts to scale the alpha channel so that a fraction `coverage` (between 0 and 1) of the surface has an alpha greater than `alphaRef`.
NVTT_API void | toRGBM (float range=1.0f, float threshold=0.25f, TimingContext *tc=0)
| Produces an LDR Red, Green, Blue, Magnitude encoding of the HDR RGB channels.
NVTT_API void | fromRGBM (float range=1.0f, float threshold=0.25f, TimingContext *tc=0)
| Produces HDR `(r, g, b, 1)` values from an LDR `(red, green, blue, magnitude)` storage method.
NVTT_API void | toLM (float range=1.0f, float threshold=0.0f, TimingContext *tc=0)
| Stores luminance-only values in a two-channel way. Maybe consider BC4 compression instead.
NVTT_API void | toRGBE (int mantissaBits, int exponentBits, TimingContext *tc=0)
| Produces a shared-exponent Red, Green, Blue, Exponent encoding of the HDR RGB channels, such as R9G9B9E5.
NVTT_API void | fromRGBE (int mantissaBits, int exponentBits, TimingContext *tc=0)
| Produces HDR `(r, g, b, 1)` values from an LDR `(red, green, blue, exponent)` storage method.
NVTT_API void | toYCoCg (TimingContext *tc=0)
| Converts from `(r, g, b, -)` colors to `(Co, Cg, 1, Y)` colors.
NVTT_API void | blockScaleCoCg (int bits=5, float threshold=0.0f, TimingContext *tc=0)
| Stores per-block YCoCg scaling information for potentially better 4-channel compression of YCoCg data.
NVTT_API void | fromYCoCg (TimingContext *tc=0)
| Converts from `(Co, Cg, scale, Y)` colors to `(r, g, b, 1)` colors.
NVTT_API void | toLUVW (float range=1.0f, TimingContext *tc=0)
| Converts from RGB colors to a (U, V, W, L) color space, much like RGBM.
NVTT_API void | fromLUVW (float range=1.0f, TimingContext *tc=0)
| Converts from toLUVW()'s color space to RGB colors.
NVTT_API void | abs (int channel, TimingContext *tc=0)
| Replaces all colors by their absolute value.
NVTT_API void | convolve (int channel, int kernelSize, float *kernelData, TimingContext *tc=0)
| Convolves a channel with a kernel.
NVTT_API void | toLogScale (int channel, float base, TimingContext *tc=0)
| Replaces all values with their log with the given base.
NVTT_API void | fromLogScale (int channel, float base, TimingContext *tc=0)
| Inverts toLogScale() by replacing all values `x` with `base^x`.
NVTT_API void | setAtlasBorder (int w, int h, float r, float g, float b, float a, TimingContext *tc=0)
| Draws borders of a given color around each w x h tile contained within the surface, starting from the (0, 0) corner.
NVTT_API void | toneMap (ToneMapper tm, float *parameters, TimingContext *tc=0)
| Applies an HDR-to-LDR tone mapper.
NVTT_API void | binarize (int channel, float threshold, bool dither, TimingContext *tc=0)
| Sets values in the given channel to either 1 or 0 depending on if they're greater than the threshold, with optional dithering.
NVTT_API void | quantize (int channel, int bits, bool exactEndPoints, bool dither, TimingContext *tc=0)
| Quantizes this channel to a particular number of bits, with optional dithering.
NVTT_API void | toNormalMap (float sm, float medium, float big, float large, TimingContext *tc=0)
| Sets the RGB channels to a normal map generated by interpreting the alpha channel as a heightmap, using a blend of four small-scale to large-scale Sobel kernels.
NVTT_API void | normalizeNormalMap (TimingContext *tc=0)
| Renormalizes the elements of a signed normal map, replacing `(r, g, b)` with `normalize(r, g, b)`.
NVTT_API void | transformNormals (NormalTransform xform, TimingContext *tc=0)
| Applies a 3D->2D normal transformation, setting the z (blue) channel to 0.
NVTT_API void | reconstructNormals (NormalTransform xform, TimingContext *tc=0)
| Reconstructs 3D normals from 2D transformed normals.
NVTT_API void | toCleanNormalMap (TimingContext *tc=0)
| Sets the z (blue) channel to x^2 + y^2.
NVTT_API void | packNormals (float scale=0.5f, float bias=0.5f, TimingContext *tc=0)
| Packs signed normals in [-1, 1] to an unsigned range [0, 1], using (r, g, b, a) |-> (r/2+1/2, g/2+1/2, b/2+1/2, a).
NVTT_API void | expandNormals (float scale=2.0f, float bias=-1.0f, TimingContext *tc=0)
| Expands packed normals in [0, 1] to signed normals in [-1, 1] using (r, g, b, a) |-> (2r-1, 2g-1, 2b-1, a).
NVTT_API Surface | createToksvigMap (float power, TimingContext *tc=0) const
| Unimplemented. This would equivalent to mipmapping a normal map and then measuring how much mipmapping shortens the normals. Currently returns a null surface.
NVTT_API Surface | createCleanMap (TimingContext *tc=0) const
| Unimplemented. Currently returns a null surface.
NVTT_API void | flipX (TimingContext *tc=0)
| Flips the surface along the X axis.
NVTT_API void | flipY (TimingContext *tc=0)
| Flips the surface along the Y axis.
NVTT_API void | flipZ (TimingContext *tc=0)
| Flips the surface along the Z axis.
NVTT_API Surface | createSubImage (int x0, int x1, int y0, int y1, int z0, int z1, TimingContext *tc=0) const
| Creates a new surface from the range of pixels from x = x0 to x1, y = y0 to y1, and z = z0 to z1.
NVTT_API bool | copyChannel (const Surface &srcImage, int srcChannel, TimingContext *tc=0)
| Copies channel `srcChannel` from `srcImage` to `srcChannel` of this surface.
NVTT_API bool | copyChannel (const Surface &srcImage, int srcChannel, int dstChannel, TimingContext *tc=0)
| Copies channel `srcChannel` from `srcImage` to `dstChannel` of this surface.
NVTT_API bool | addChannel (const Surface &img, int srcChannel, int dstChannel, float scale, TimingContext *tc=0)
| Add channel `srcChannel` of `img`, multiplied by `scale`, to `dstChannel` of this surface.
NVTT_API bool | copy (const Surface &src, int xsrc, int ysrc, int zsrc, int xsize, int ysize, int zsize, int xdst, int ydst, int zdst, TimingContext *tc=0)
| Copies all channels of a rectangle from `src` to this surface.
NVTT_API void | ToGPU (TimingContext *tc=0, bool performCopy=true)
| Makes succeeding operations work on the GPU buffer.
NVTT_API void | ToCPU (TimingContext *tc=0)
| Makes succeeding operations work on the CPU buffer.
NVTT_API const float * | gpuData () const
| Get a CUDA pointer to const image data on the GPU, using the same layout as data(). If GPU data does not exist, returns `nullptr`.
NVTT_API float * | gpuDataMutable ()
| Get a CUDA pointer to non-const image data on the GPU, using the same layout as data(). If GPU data does not exist, returns `nullptr`. This can be used to modify NVTT Surface data on the GPU, outside of the functions NVTT provides.
void | detach ()

## Public Attributes

Private * | m

## Detailed Description

A surface is one level of a 2D or 3D texture.

A surface has four channels numbered 0-3, also referred to as the red, green, blue, and alpha channels.

Surfaces store some additional properties, such as their width, height, depth, wrap mode, alpha mode, and whether they represent a normal map.

Surfaces can have CPU and GPU data. If a surface has GPU data, it always has CPU data. When the surface is GPU-enabled (using ToGPU()), image processing will be CUDA-accelerated and work on this GPU data. Calling ToCPU() will copy the GPU data to the CPU and destroy the GPU data buffer. `gpuData() != nullptr` can be used to determine if a surface has GPU data.

To directly access CPU data, use data() or channel(). To get a pointer to the GPU data buffer, use gpuData() (for a const CUDA pointer) or gpuDataMutable() (for a CUDA pointer to modifiable data).

Texture data is stored non-interleaved; that is, all channel 0's data is stored first, followed by channel 1's, and so on.

Note
  Performance note: Surfaces use reference-counted pointers to image data. This means that multiple Surfaces can reference the same data. This is handled automatically by NVTT's image processing routines. For instance, after the following piece of code,
  nvtt::Surface s1;
  s1.setImage(...);
  nvtt::Surface s2 = s1;
  nvtt::Surface
  A surface is one level of a 2D or 3D texture.
  Definition nvtt.h:698
  nvtt::Surface::setImage
  NVTT_API bool setImage(int w, int h, int d, TimingContext *tc=0)
  Sets this surface to a new w x h x d uninitialized image.
  surfaces `s1` and `s2` will have the same `data()` pointer. Cloning the underlying data is handled automatically: for instance, after
  s2.toSrgb()
  nvtt::Surface::toSrgb
  NVTT_API void toSrgb(TimingContext *tc=0)
  Applies the linear-to-sRGB transfer function to channels 0...2.
  `s2` will have a new `data()` pointer, and `s1` will be unchanged. This usually means that when writing custom image processing routines, you'll want to call Surface::clone() before modifying the Surface's data. Using Nsight Systems is one way to detect when additional allocations occur.

Since
  NVTT 2.1

## Member Function Documentation

## ◆ addChannel()

NVTT_API bool nvtt::Surface::addChannel | ( | const Surface & | img,
|  | int | srcChannel,
|  | int | dstChannel,
|  | float | scale,
|  | TimingContext * | tc = 0 )

Add channel `srcChannel` of `img`, multiplied by `scale`, to `dstChannel` of this surface.

Returns whether the operation succeeded (for instance, it can fail if the surfaces have different sizes).

Both `srcChannel` and `dstChannel` must be in the range [0, 3].

The surfaces need not have the same GPU mode.

## ◆ alphaTestCoverage()

NVTT_API float nvtt::Surface::alphaTestCoverage | ( | float | alphaRef = 0.5,
|  | int | alpha_channel = 3 ) const

Returns the approximate fraction (0 to 1) of the image with an alpha value greater than `alphaRef`.

This function uses 8 x 8 subsampling together with linear interpolation.

Note
  `alphaRef` is clamped to the range [1/256, 255/256].

## ◆ average()

NVTT_API float nvtt::Surface::average | ( | int | channel,
|  | int | alpha_channel = -1,
|  | float | gamma = 2.2f ) const

Computes the average of a channel, possibly with alpha or with a gamma transfer function.

If `alpha_channel` is -1, this function computes

`(sum(c[i]^gamma, i=0...numPixels)/numPixels)^(1/gamma)`

where `c` is the channel's data.

Otherwise, this computes

`(sum((c[i]^gamma) * a[i], i=0...numPixels)/sum(a[i], i=0...numPixels))^(1/gamma)`

where `a` is the alpha channel's data.

Parameters

  channel | The channel to average.
  alpha_channel | If not equal to -1, weights each texel's value after gamma correction by this channel.
  gamma | Gamma for the transfer function to apply. A value of 2.2f roughly corresponds to averaging an sRGB image in linear space, then converting back to sRGB.

## ◆ binarize()

NVTT_API void nvtt::Surface::binarize | ( | int | channel,
|  | float | threshold,
|  | bool | dither,
|  | TimingContext * | tc = 0 )

Sets values in the given channel to either 1 or 0 depending on if they're greater than the threshold, with optional dithering.

Parameters

  dither | If true, uses Floyd-Steinberg dithering on the CPU. Not supported for 3D surfaces.

## ◆ blend()

NVTT_API void nvtt::Surface::blend | ( | float | r,
|  | float | g,
|  | float | b,
|  | float | a,
|  | float | t,
|  | TimingContext * | tc = 0 )

Interpolates all texels between their current color and a constant color `(r, g, b, a)`.

`t` is the value used for linearly interpolating between the surface's current colors and the constant color. For instance, a value of `t=0` has no effect to the surface's colors, and a value of `t=1` replaces the surface's colors entirely with (r, g, b, a).

## ◆ blockScaleCoCg()

NVTT_API void nvtt::Surface::blockScaleCoCg | ( | int | bits = 5,
|  | float | threshold = 0.0f,
|  | TimingContext * | tc = 0 )

Stores per-block YCoCg scaling information for potentially better 4-channel compression of YCoCg data.

For each 4x4 block, this computes the maximum absolute Co and Cg values, stores the result in the blue channel, and multiplies the Co and Cg channels (0 and 1) by its reciprocal. The original Co and Cg values can then be reconstructed by multiplying by the blue channel.

The scaling information is quantized to the given number of bits.

`threshold` is ignored.

Note
  This assumes that your texture compression format uses 4x4 blocks. This is true for all BC1-BC7 formats, but ASTC can use other block sizes.

## ◆ buildNextMipmap() [1/2]

NVTT_API bool nvtt::Surface::buildNextMipmap | ( | MipmapFilter | filter,
|  | float | filterWidth,
|  | const float * | params = 0,
|  | int | min_size = 1,
|  | TimingContext * | tc = 0 )

Version of buildNextMipmap(MipmapFilter, int, TimingContext*) with customizable parameters.

See also
  MipmapFilter for the effects of different parameters.

## ◆ buildNextMipmap() [2/2]

NVTT_API bool nvtt::Surface::buildNextMipmap | ( | MipmapFilter | filter,
|  | int | min_size = 1,
|  | TimingContext * | tc = 0 )

Resizes this surface to create the next mip in a mipmap chain.

Returns false iff the next mip would have been smaller than `min_size` (signaling the end of the mipmap chain).

## ◆ buildNextMipmapSolidColor()

NVTT_API bool nvtt::Surface::buildNextMipmapSolidColor | ( | const float *const | color_components,
|  | TimingContext * | tc = 0 )

Replaces this surface with a surface the size of the next mip in a mip chain (half the width and height), but with each channel cleared to a constant value.

Parameters

  color_components | is an array of the value for each channel; it must be at least as long as the number of channels in the surface.

## ◆ canMakeNextMipmap()

NVTT_API bool nvtt::Surface::canMakeNextMipmap | ( | int | min_size = 1 | ) |

Returns whether a the surface would have a next mip in a mip chain with minimum size `min_size.

That is, it returns false if this surface has size 1x1x1, or if the width and height are less than `min_size` and the depth is 1.

## ◆ channel()

NVTT_API const float * nvtt::Surface::channel | ( | int | i | ) | const

Returns a `const` pointer to channel i's CPU data.

Data is stored in [z, y, x] order; that is, all channel 0's data comes first, followed by all channel 1's data, and so on. More specifically, the value of channel c of the texel at (x, y, z) is at index

`(z * height() + y) * width() + x`

of channel(c).

Note
  If the image has GPU data (see ToGPU()), this performs a GPU-to-CPU copy.

## ◆ convolve()

NVTT_API void nvtt::Surface::convolve | ( | int | channel,
|  | int | kernelSize,
|  | float * | kernelData,
|  | TimingContext * | tc = 0 )

Convolves a channel with a kernel.

This uses a 2D kernelSize x kernelSize kernel, with values in `kernelData` specified in row-major order. The behavior around image borders is determined by the image's wrap mode.

## ◆ copy()

NVTT_API bool nvtt::Surface::copy | ( | const Surface & | src,
|  | int | xsrc,
|  | int | ysrc,
|  | int | zsrc,
|  | int | xsize,
|  | int | ysize,
|  | int | zsize,
|  | int | xdst,
|  | int | ydst,
|  | int | zdst,
|  | TimingContext * | tc = 0 )

Copies all channels of a rectangle from `src` to this surface.

More specifically, this copies the rectangle

`[xsrc, xsrc + xsize - 1] x [ysrc, ysrc + ysize - 1] x [zsrc, zsrc + zsize - 1]`

to the rectangle

`[xdst, xdst + xsize - 1] x [ydst, ydst + ysize - 1] x [zdst, zdst + zsize - 1]`.

Returns whether the operation succeeded (for instance, invalid parameters return false).

## ◆ copyChannel() [1/2]

NVTT_API bool nvtt::Surface::copyChannel | ( | const Surface & | srcImage,
|  | int | srcChannel,
|  | int | dstChannel,
|  | TimingContext * | tc = 0 )

Copies channel `srcChannel` from `srcImage` to `dstChannel` of this surface.

Returns whether the operation succeeded (for instance, it can fail if the surfaces have different sizes).

Both `srcChannel` and `dstChannel` must be in the range [0, 3].

The surfaces need not have the same GPU mode.

## ◆ copyChannel() [2/2]

NVTT_API bool nvtt::Surface::copyChannel | ( | const Surface & | srcImage,
|  | int | srcChannel,
|  | TimingContext * | tc = 0 )

Copies channel `srcChannel` from `srcImage` to `srcChannel` of this surface.

Returns whether the operation succeeded (for instance, it can fail if the surfaces have different sizes).

`srcChannel` must be in the range [0, 3].

The surfaces need not have the same GPU mode.

## ◆ countMipmaps() [1/2]

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

Returns the number of mipmaps in a full mipmap chain. Each mip is half the size of the previous, rounding down, until and including a 1x1 mip.

For instance, a 8x5 surface has mipmaps of size 8x5 (mip 0), 4x2 (mip 1), 2x1 (mip 2), and 1x1 (mip 3), so countMipmaps() returns 4. A 7x3 surface has mipmaps of size 7x3, 3x1, and 1x1, so countMipmaps() returns 3.

## ◆ countMipmaps() [2/2]

NVTT_API int nvtt::Surface::countMipmaps | ( | int | min_size | ) | const

Returns the number of mipmaps in a mipmap chain, stopping when canMakeNextMipmap() returns false.

That is, it stops when a 1x1x1 mip is reached if `min_size == 1` (in which case it is the same as countMipmaps()), or stops when the width and height are less than `min_size` and the depth is 1.

See also
  canMakeNextMipmap().

## ◆ createCleanMap()

NVTT_API Surface nvtt::Surface::createCleanMap | ( | TimingContext * | tc = 0 | ) | const

Unimplemented. Currently returns a null surface.

See also
  toCleanNormalMap()

## ◆ createSubImage()

NVTT_API Surface nvtt::Surface::createSubImage | ( | int | x0,
|  | int | x1,
|  | int | y0,
|  | int | y1,
|  | int | z0,
|  | int | z1,
|  | TimingContext * | tc = 0 ) const

Creates a new surface from the range of pixels from x = x0 to x1, y = y0 to y1, and z = z0 to z1.

If any of the parameters are out of bounds or creation fails, returns a null surface.

A valid surface created will have size (x1 - x0 + 1) x (y1 - y0 + 1) x (z1 - z0 + 1).

## ◆ createToksvigMap()

NVTT_API Surface nvtt::Surface::createToksvigMap | ( | float | power,
|  | TimingContext * | tc = 0 ) const

Unimplemented. This would equivalent to mipmapping a normal map and then measuring how much mipmapping shortens the normals. Currently returns a null surface.

See also
  Hill, "Specular Showdown in the Wild West", http://blog.selfshadow.com/2011/07/22/specular-showdown/

## ◆ data()

NVTT_API const float * nvtt::Surface::data | ( |  | ) | const

Returns a `const` pointer to the surface's CPU data.

Data is stored in [c, z, y, x] order; that is, all channel 0's data comes first, followed by all channel 1's data, and so on. More specifically, the value of channel c of the texel at (x, y, z) is at index

`((c * depth() + z) * height() + y) * width() + x`.

Note
  If the image has GPU data (see ToGPU()), this performs a GPU-to-CPU copy.

## ◆ demultiplyAlpha()

NVTT_API void nvtt::Surface::demultiplyAlpha | ( | float | epsilon = 1e-12f,
|  | TimingContext * | tc = 0 )

Converts from premultiplied to unpremultiplied alpha, with special handling around zero alpha values.

When `abs(a) >= epsilon`, the result is the same as dividing the RGB channels by the alpha channel. Otherwise, this function divides the RGB channels by `epsilon * sign(a)`, since the result of unpremultiplying a fully transparent color is undefined.

## ◆ fromLUVW()

NVTT_API void nvtt::Surface::fromLUVW | ( | float | range = 1.0f,
|  | TimingContext * | tc = 0 )

Converts from toLUVW()'s color space to RGB colors.

This is the same as fromRGBM(range * sqrt(3)).

## ◆ fromRGBE()

NVTT_API void nvtt::Surface::fromRGBE | ( | int | mantissaBits,
|  | int | exponentBits,
|  | TimingContext * | tc = 0 )

Produces HDR `(r, g, b, 1)` values from an LDR `(red, green, blue, exponent)` storage method.

HDR values are reconstructed as follows: R, G, B, and E are first converted from UNORM floats to integers by multiplying RGB by `(1 << mantissaBits) - 1` and E by `(1 << exponentBits) - 1`. E stores a scaling factor as a power of 2, which is reconstructed using `scale = 2^(E - ((1 << (exponentBits - 1)) - 1) - mantissaBits)`. R, G, and B are then multiplied by `scale`.

`mantissaBits` and `exponentBits` must be in the range 1...31.

## ◆ fromRGBM()

NVTT_API void nvtt::Surface::fromRGBM | ( | float | range = 1.0f,
|  | float | threshold = 0.25f,
|  | TimingContext * | tc = 0 )

Produces HDR `(r, g, b, 1)` values from an LDR `(red, green, blue, magnitude)` storage method.

HDR values are reconstructed as follows: First, the magnitude `M` is reconstructed from the alpha channel using `M = a * (range - threshold) + threshold`. Then the red, green, and blue channels are multiplied by `M`.

## ◆ fromYCoCg()

NVTT_API void nvtt::Surface::fromYCoCg | ( | TimingContext * | tc = 0 | ) |

Converts from `(Co, Cg, scale, Y)` colors to `(r, g, b, 1)` colors.

This is useful for formats that use chroma subsampling.

Y is in the range [0, 1], while Co and Cg are in the range [-1, 1]. Co and Cg are multiplied by channel 2 (scale) to reverse the effects of optionally calling blockScaleCoCg().

The YCoCg-to-RGB formula used is

r = Y + Co - Cg
g = Y + Cg
b = Y - Co - Cg

## ◆ gpuDataMutable()

NVTT_API float * nvtt::Surface::gpuDataMutable | ( |  | ) |

Get a CUDA pointer to non-const image data on the GPU, using the same layout as data(). If GPU data does not exist, returns `nullptr`. This can be used to modify NVTT Surface data on the GPU, outside of the functions NVTT provides.

Since
  NVTT 3.2

## ◆ histogram()

NVTT_API void nvtt::Surface::histogram | ( | int | channel,
|  | float | rangeMin,
|  | float | rangeMax,
|  | int | binCount,
|  | int * | binPtr,
|  | TimingContext * | tc = 0 ) const

Stores a histogram of channel values between `rangeMin` and `rangeMax` into `binPtr[0...binCount-1]`.

`binPtr` must be an array of at least `binCount` integers. This function does not clear `binPtr`'s values, in case we want to accumulate multiple histograms.

Each texel's value is linearly mapped to a bin, using floor rounding. Values below `rangeMin` are clamped to bin 0, values above `rangeMax` are clamped to bin `binCount-1`. Then the bin's value is incremented.

## ◆ load()

NVTT_API bool nvtt::Surface::load | ( | const char * | fileName,
|  | bool * | hasAlpha = 0,
|  | bool | expectSigned = false,
|  | TimingContext * | tc = 0 )

Loads texture data from a file.

Returns
  `true` if loading succeeded and `false` if it failed.

Parameters

  fileName | Path to the file to load. This uses the same character encoding as the `filename` argument of `fopen()`.
  hasAlpha | If this is non-null, then `*hasAlpha` will be set to whether the reader reported that the file included an alpha channel.
  expectSigned | If this is true, then some forms of unsigned data will be converted to signed using the mapping x |-> 2x-1.

## ◆ loadFromMemory()

NVTT_API bool nvtt::Surface::loadFromMemory | ( | const void * | data,
|  | unsigned long long | sizeInBytes,
|  | bool * | hasAlpha = 0,
|  | bool | expectSigned = false,
|  | TimingContext * | tc = 0 )

Variant of load() that reads from memory instead of a file.

Returns
  `true` if loading succeeded and `false` if it failed.

Parameters

  data | Pointer to the start of the file's data in memory.
  sizeInBytes | Length of the file's data.
  hasAlpha | If this is non-null, then `*hasAlpha` will be set to whether the reader reported that the file included an alpha channel.
  expectSigned | If this is true, then some forms of unsigned data will be converted to signed using the mapping x |-> 2x-1.

## ◆ normalizeNormalMap()

NVTT_API void nvtt::Surface::normalizeNormalMap | ( | TimingContext * | tc = 0 | ) |

Renormalizes the elements of a signed normal map, replacing `(r, g, b)` with `normalize(r, g, b)`.

This function is safe to call even for zero vectors.

## ◆ quantize()

NVTT_API void nvtt::Surface::quantize | ( | int | channel,
|  | int | bits,
|  | bool | exactEndPoints,
|  | bool | dither,
|  | TimingContext * | tc = 0 )

Quantizes this channel to a particular number of bits, with optional dithering.

Parameters

  channel | The index of the channel to quantize.
  bits | The number of bits to quantize to, yielding `2^bits` possible values. Must be nonnegative, and must not be 0 if exactEndPoints is true.
  exactEndPoints | If true, the set of quantized values will be `0, 1/(2^bits-1), ..., 1`, rather than `0, 1/(2^bits), ..., (2^bits-1)/(2^bits)`.
  dither | If true, uses Floyd-Steinberg dithering on the CPU. Not supported for 3D surfaces.

## ◆ range()

NVTT_API void nvtt::Surface::range | ( | int | channel,
|  | float * | rangeMin,
|  | float * | rangeMax,
|  | int | alpha_channel = -1,
|  | float | alpha_ref = 0.f,
|  | TimingContext * | tc = 0 ) const

Sets `*rangeMin` and `*rangeMax` to the range of values in the channel, possibly using alpha testing.

If `alpha_channel` is -1, this sets `*rangeMin` to the smallest value in the entire channel, and `*rangeMax` to the largest value in the entire channel. Otherwise, this only includes texels for which the alpha value is greater than `alpha_ref`.

If the image is null or if an alpha channel is selected and all texels fail the alpha test, this sets `*rangeMin` to `FLT_MAX` and `*rangeMax` to `FLT_MIN`, i.e. one will have `*rangeMin > *rangeMax`.

## ◆ reconstructNormals()

NVTT_API void nvtt::Surface::reconstructNormals | ( | NormalTransform | xform,
|  | TimingContext * | tc = 0 )

Reconstructs 3D normals from 2D transformed normals.

See also
  NormalTransform for definitions of each of the normal transformations.

## ◆ resize() [1/3]

NVTT_API void nvtt::Surface::resize | ( | int | maxExtent,
|  | RoundMode | mode,
|  | ResizeFilter | filter,
|  | float | filterWidth,
|  | const float * | params = 0,
|  | TimingContext * | tc = 0 )

Resizes this surface so that its largest side has length `maxExtent`, subject to a rounding mode, using customizable filter parameters.

See also
  getTargetExtent()

## ◆ resize() [2/3]

NVTT_API void nvtt::Surface::resize | ( | int | maxExtent,
|  | RoundMode | mode,
|  | ResizeFilter | filter,
|  | TimingContext * | tc = 0 )

Resizes this surface so that its largest side has length `maxExtent`, subject to a rounding mode.

See also
  getTargetExtent()

## ◆ resize() [3/3]

NVTT_API void nvtt::Surface::resize | ( | int | w,
|  | int | h,
|  | int | d,
|  | ResizeFilter | filter,
|  | float | filterWidth,
|  | const float * | params = 0,
|  | TimingContext * | tc = 0 )

Resizes this surface using customizable filter parameters.

See also
  ResizeFilter for filter-specific parameters.

## ◆ resize_make_square()

NVTT_API void nvtt::Surface::resize_make_square | ( | int | maxExtent,
|  | RoundMode | roundMode,
|  | ResizeFilter | filter,
|  | TimingContext * | tc = 0 )

Resizes this surface so that its longest side has length `maxExtent` and the result is square or cubical.

For 2D surfaces, the size is determined using getTargetExtent(), then using the minimum of the width and height. For 3D surfaces, the size is similarly determined using getTargetExtent(), then using the minimum of the width, height, or depth.

## ◆ save()

NVTT_API bool nvtt::Surface::save | ( | const char * | fileName,
|  | bool | hasAlpha = false,
|  | bool | hdr = false,
|  | TimingContext * | tc = 0 ) const

Saves texture data to file.

Returns
  `true` if saving succeeded and `false` if it failed.

Parameters

  fileName | Path to the file to load. This uses the same character encoding as the `filename` argument of `fopen()`.
  hasAlpha | If true, then TGA images will be saved with an alpha channel.
  hdr | If true, then this will attempt to use a writer that supports an HDR format before attempting to use an LDR format writer.

## ◆ scaleAlphaToCoverage()

NVTT_API void nvtt::Surface::scaleAlphaToCoverage | ( | float | coverage,
|  | float | alphaRef = 0.5f,
|  | int | alpha_channel = 3,
|  | TimingContext * | tc = 0 )

Attempts to scale the alpha channel so that a fraction `coverage` (between 0 and 1) of the surface has an alpha greater than `alphaRef`.

See also
  alphaTestCoverage() for the method used to determine what fraction passes the alpha test.
  Ignacio Castaño, "Computing Alpha Mipmaps" (2010)

## ◆ setAtlasBorder()

NVTT_API void nvtt::Surface::setAtlasBorder | ( | int | w,
|  | int | h,
|  | float | r,
|  | float | g,
|  | float | b,
|  | float | a,
|  | TimingContext * | tc = 0 )

Draws borders of a given color around each w x h tile contained within the surface, starting from the (0, 0) corner.

In case the surface size is not divisible by the tile size, borders are not drawn for tiles crossing the surface boundary.

## ◆ setImage() [1/3]

NVTT_API bool nvtt::Surface::setImage | ( | InputFormat | format,
|  | int | w,
|  | int | h,
|  | int | d,
|  | const void * | data,
|  | bool | unsignedToSigned = false,
|  | TimingContext * | tc = 0 )

Sets this surface given uncompressed input data.

The type of values in `data` should match `format`.

If `unsignedToSigned` is true, InputFormat_BGRA_8UB unsigned input will be converted to signed values between -1 and 1, mapping 0 to -1, and 1...255 linearly to -1...1.

Returns whether setting the image succeeded.

See also
  setImage(int, int, int, TimingContext*)

## ◆ setImage() [2/3]

NVTT_API bool nvtt::Surface::setImage | ( | InputFormat | format,
|  | int | w,
|  | int | h,
|  | int | d,
|  | const void * | r,
|  | const void * | g,
|  | const void * | b,
|  | const void * | a,
|  | TimingContext * | tc = 0 )

Sets this surface given uncompressed input data, with different pointers for each channel.

The type of values in `data` should match `format`.

Returns whether setting the image succeeded.

See also
  setImage(int, int, int, TimingContext*)

## ◆ setImage() [3/3]

NVTT_API bool nvtt::Surface::setImage | ( | int | w,
|  | int | h,
|  | int | d,
|  | TimingContext * | tc = 0 )

Sets this surface to a new w x h x d uninitialized image.

Surfaces are not GPU-enabled by default. The surface's texture type will be set to TextureType_2D if `d == 1`, and TextureType_3D otherwise.

Returns
  `true`

## ◆ setImage3D()

NVTT_API bool nvtt::Surface::setImage3D | ( | Format | format,
|  | int | w,
|  | int | h,
|  | int | d,
|  | const void * | data,
|  | TimingContext * | tc = 0 )

Set surface values from an encoded data source.

For instance, this can be used to decompress BC1-BC7 or ASTC data.

Returns whether setting the image succeeded.

## ◆ swizzle()

NVTT_API void nvtt::Surface::swizzle | ( | int | r,
|  | int | g,
|  | int | b,
|  | int | a,
|  | TimingContext * | tc = 0 )

Swizzles the channels of the surface.

Each argument specifies where the corresponding channel should come from. For instance, setting r to 2 would mean that the red (0) channel would be set to the current 2nd channel.

In addition, the special values 4, 5, and 6 represent setting the channel to a constant value of 1.0f, 0.0f, or -1.0f, respectively.

## ◆ toCleanNormalMap()

NVTT_API void nvtt::Surface::toCleanNormalMap | ( | TimingContext * | tc = 0 | ) |

Sets the z (blue) channel to x^2 + y^2.

If the x and y channels represent slopes, instead of normals, then this represents a CLEAN map. The important thing about this is that it can be mipmapped, and the difference between the sum of the square of the first and second mipmapped channels and the third mipmapped channel can be used to determine how rough the normal map is in a given area.

This is a lower-memory and lower-bandwidth version of LEAN mapping, but it has the drawback that it can only represent isotropic roughness.

See also
  Olano and Baker, "LEAN Mapping", https://www.csee.umbc.edu/~olano/papers/lean/
  Hill, "Specular Showdown in the Wild West", http://blog.selfshadow.com/2011/07/22/specular-showdown/
  http://gaim.umbc.edu/2011/07/24/shiny-and-clean/
  http://gaim.umbc.edu/2011/07/26/on-error/

## ◆ ToCPU()

NVTT_API void nvtt::Surface::ToCPU | ( | TimingContext * | tc = 0 | ) |

Makes succeeding operations work on the CPU buffer.

This copies the surface's GPU buffer to the CPU buffer, then destroys the GPU buffer.

Since
  NVTT 3.0

## ◆ toGamma() [1/2]

NVTT_API void nvtt::Surface::toGamma | ( | float | gamma,
|  | TimingContext * | tc = 0 )

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

`gamma=2.2` approximates linear-to-sRGB conversion.

See also
  toLinear()
  toSrgb()

## ◆ toGamma() [2/2]

NVTT_API void nvtt::Surface::toGamma | ( | int | channel,
|  | float | gamma,
|  | TimingContext * | tc = 0 )

Raises the given channel to the power `1/gamma`.

See also
  toGamma(float, TimingContext*)

## ◆ ToGPU()

NVTT_API void nvtt::Surface::ToGPU | ( | TimingContext * | tc = 0,
|  | bool | performCopy = true )

Makes succeeding operations work on the GPU buffer.

This also copies the surface's CPU data to a new or recreated GPU buffer.

Since
  NVTT 3.0

## ◆ toGreyScale()

NVTT_API void nvtt::Surface::toGreyScale | ( | float | redScale,
|  | float | greenScale,
|  | float | blueScale,
|  | float | alphaScale,
|  | TimingContext * | tc = 0 )

Sets channels 0...3 to the result of converting to grayscale, with customizable channel weights.

For instance, this can be used to give green a higher weight than red or blue when computing luminance. This function will normalize the different scales so they sum to 1, so e.g. (2, 4, 1, 0) are valid scales. The greyscale value is then computed using

grey = r * redScale + g * greenScale + b * blueScale + a * alphaScale

and then all channels (including alpha) are set to `grey`.

## ◆ toLinear() [1/2]

NVTT_API void nvtt::Surface::toLinear | ( | float | gamma,
|  | TimingContext * | tc = 0 )

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

`gamma=2.2` approximates sRGB-to-linear conversion.

See also
  toGamma()
  toLinearFromSrgb()

## ◆ toLinear() [2/2]

NVTT_API void nvtt::Surface::toLinear | ( | int | channel,
|  | float | gamma,
|  | TimingContext * | tc = 0 )

Raises the given channel to the power `gamma`.

See also
  toLinear(float, TimingContext*)

## ◆ toLinearFromSrgb()

NVTT_API void nvtt::Surface::toLinearFromSrgb | ( | TimingContext * | tc = 0 | ) |

Applies the sRGB-to-linear transfer function to channels 0...2.

This transfer function replaces each value `x` with

if x < 0.0f, 0.0f
if x < 0.04045f, x / 12.92f
if x < 1.0f, powf((x + 0.055f)/1.055f, 2.4f)
otherwise, 1.0f

See also
  toSrgb()

## ◆ toLinearFromSrgbUnclamped()

NVTT_API void nvtt::Surface::toLinearFromSrgbUnclamped | ( | TimingContext * | tc = 0 | ) |

Applies the sRGB-to-linear transfer function to channels 0...2, but does not clamp output to [0,1].

The motivation for this function is that it can approximately preserve HDR values through sRGB conversion and back; that is, s.toSrgbUnclamped().toLinearFromSrgbUnclamped() is close to s.

This transfer function replaces each value `x` with

if x is NaN or x <= 0.0f, x
if x < 0.04045f, x / 12.92f
otherwise, powf((x + 0.055f)/1.055f, 2.4f)

Since
  NVTT 3.2

See also
  toSrgbUnclamped()

## ◆ toLinearFromXenonSrgb()

NVTT_API void nvtt::Surface::toLinearFromXenonSrgb | ( | TimingContext * | tc = 0 | ) |

Converts colors in channels 0...2 from the Xenon sRGB piecewise linear sRGB approximation to linear.

This transfer function replaces each value `x` with

if x < 0, 0.0f
if x < 1/4, x/4.0f
if x < 3/8, (x - 0.125f) / 2.0f
if x < 3/4, x - 0.25f
if x < 1, (x - 0.5f) / 0.5f
otherwise, 1.0f

Since
  NVTT 3.2

See also
  Alex Vlachos, Post Processing in The Orange Box, GDC 2008
  toXenonSrgb()

## ◆ toLM()

NVTT_API void nvtt::Surface::toLM | ( | float | range = 1.0f,
|  | float | threshold = 0.0f,
|  | TimingContext * | tc = 0 )

Stores luminance-only values in a two-channel way. Maybe consider BC4 compression instead.

Luminance `L` is computed by averaging the red, green, and blue values, while `M` stores the max of these values and `threshold`. The red, green, and blue channels then store `L/M`, and the alpha channel stores `(M - threshold)/(1 - threshold)`.

## ◆ toLUVW()

NVTT_API void nvtt::Surface::toLUVW | ( | float | range = 1.0f,
|  | TimingContext * | tc = 0 )

Converts from RGB colors to a (U, V, W, L) color space, much like RGBM.

All values are clamped to [0, 1]. Then a luminance-like value `L` is computed from RGB using

`L = max(sqrtf(R^2 + G^2 + B^2), 1e-6f)`.

This then stores the value `(R/L, G/L, B/L, L/sqrt(3))`.

## ◆ toneMap()

NVTT_API void nvtt::Surface::toneMap | ( | ToneMapper | tm,
|  | float * | parameters,
|  | TimingContext * | tc = 0 )

Applies an HDR-to-LDR tone mapper.

See also
  ToneMapper for definitions of the tone mappers.

## ◆ toNormalMap()

NVTT_API void nvtt::Surface::toNormalMap | ( | float | sm,
|  | float | medium,
|  | float | big,
|  | float | large,
|  | TimingContext * | tc = 0 )

Sets the RGB channels to a normal map generated by interpreting the alpha channel as a heightmap, using a blend of four small-scale to large-scale Sobel kernels.

This uses a 9x9 kernel which is a weighted sum of a 3x3 (small), 5x5 (medium), 7x7 (big), and 9x9 (large) differentiation kernels. Each of the weights can be greater than 1, or even negative. However, the kernel will be normalized so that its elements sum to 1, so scaling should be done on the alpha channel beforehand. The smallest kernel focuses on the highest-frequency details, and larger kernels attenuate higher frequencies.

The source alpha channel, which is used as a height map to differentiate, is copied to the output.

The output RGB channels will be in the ranges [-1, 1], [-1, 1], and [0, 1].

See also
  convolve()

## ◆ toRGBE()

NVTT_API void nvtt::Surface::toRGBE | ( | int | mantissaBits,
|  | int | exponentBits,
|  | TimingContext * | tc = 0 )

Produces a shared-exponent Red, Green, Blue, Exponent encoding of the HDR RGB channels, such as R9G9B9E5.

`mantissaBits` and `exponentBits` must be in the range 1...31.

See fromRGBE() for the storage method. This uses an iterative compression approach to reduce the error with regard to decoding.

## ◆ toRGBM()

NVTT_API void nvtt::Surface::toRGBM | ( | float | range = 1.0f,
|  | float | threshold = 0.25f,
|  | TimingContext * | tc = 0 )

Produces an LDR Red, Green, Blue, Magnitude encoding of the HDR RGB channels.

See fromRGBM() for the storage method. This uses an iterative compression approach to reduce the error with regard to decoding.

## ◆ toSrgb()

NVTT_API void nvtt::Surface::toSrgb | ( | TimingContext * | tc = 0 | ) |

Applies the linear-to-sRGB transfer function to channels 0...2.

This transfer function replaces each value `x` with

if x is NaN or x <= 0.0f, 0.0f
if x <= 0.0031308f, 12.92f * x
if x < 1.0f, powf(x, 1.0f/2.4f) * 1.055f - 0.055f
otherwise, 1.0f

See also
  toLinearFromSrgb()

## ◆ toSrgbUnclamped()

NVTT_API void nvtt::Surface::toSrgbUnclamped | ( | TimingContext * | tc = 0 | ) |

Applies the linear-to-sRGB transfer function to channels 0...2, but does not clamp output to [0,1].

The motivation for this function is that it can approximately preserve HDR values through sRGB conversion and back; that is, s.toSrgbUnclamped().toLinearFromSrgbUnclamped() is close to s.

This transfer function replaces each value `x` with

if x is NaN or x <= 0.0f, x
if x <= 0.0031308f, 12.92f * x
otherwise, powf(x, 1.0f/2.4f) * 1.055f - 0.055f

Since
  NVTT 3.2

See also
  toLinearFromSrgbUnclamped()

## ◆ toXenonSrgb()

NVTT_API void nvtt::Surface::toXenonSrgb | ( | TimingContext * | tc = 0 | ) |

Converts colors in channels 0...2 from linear to a piecewise linear sRGB approximation.

This transfer function replaces each value `x` with

if x < 0, 0.0f
if x < 1/16, 4.0f * x
if x < 1/8, 2.0f * x + 0.125f
if x < 1/2, x + 0.25f
if x < 1, 0.5f * x + 0.5f
otherwise, 1.0f

See also
  Alex Vlachos, Post Processing in The Orange Box, GDC 2008
  toLinearFromXenonSrgb()

## ◆ toYCoCg()

NVTT_API void nvtt::Surface::toYCoCg | ( | TimingContext * | tc = 0 | ) |

Converts from `(r, g, b, -)` colors to `(Co, Cg, 1, Y)` colors.

This is useful for formats that use chroma subsampling.

Y is in the range [0, 1], while Co and Cg are in the range [-1, 1].

The RGB-to-YCoCg formula used is

Y = (2g + r + b)/4
Co = r - b
Cg = (2g - r - b)/2

## ◆ transform()

NVTT_API void nvtt::Surface::transform | ( | const float | w0[4],
|  | const float | w1[4],
|  | const float | w2[4],
|  | const float | w3[4],
|  | const float | offset[4],
|  | TimingContext * | tc = 0 )

Applies a 4x4 affine transformation to the values in channels 0...3.

`w0`...`w3` are the columns of the matrix. `offset` is added after the matrix-vector multiplication.

In other words, all (r, g, b, a) values are replaced with

(r) (w0[0], w1[0], w2[0], w3[0]) (r) (offset[0])
(g) = (w0[1], w1[1], w2[1], w3[1]) (g) + (offset[1])
(b) (w0[2], w1[2], w2[2], w3[2]) (b) (offset[2])
(a) (w0[3], w1[3], w2[3], w3[3]) (a) (offset[3])

## ◆ transformNormals()

NVTT_API void nvtt::Surface::transformNormals | ( | NormalTransform | xform,
|  | TimingContext * | tc = 0 )

Applies a 3D->2D normal transformation, setting the z (blue) channel to 0.

See also
  NormalTransform for definitions of each of the normal transformations.

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

- nvtt/nvtt.h