nvtt
|
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 |
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.
s1
and s2
will have the same data()
pointer. Cloning the underlying data is handled automatically: for instance, after 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.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.
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.
alphaRef
is clamped to the range [1/256, 255/256]. 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.
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. |
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.
dither | If true, uses Floyd-Steinberg dithering on the CPU. Not supported for 3D surfaces. |
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).
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.
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.
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).
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.
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. |
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.
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).
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.
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).
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.
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.
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.
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.
NVTT_API Surface nvtt::Surface::createCleanMap | ( | TimingContext * | tc = 0 | ) | const |
Unimplemented. Currently returns a null surface.
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).
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.
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
.
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.
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)).
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.
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
.
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
NVTT_API float * nvtt::Surface::gpuDataMutable | ( | ) |
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.
NVTT_API bool nvtt::Surface::load | ( | const char * | fileName, |
bool * | hasAlpha = 0, | ||
bool | expectSigned = false, | ||
TimingContext * | tc = 0 ) |
Loads texture data from a file.
true
if loading succeeded and false
if it failed.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. |
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.
true
if loading succeeded and false
if it failed.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. |
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.
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.
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. |
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
.
NVTT_API void nvtt::Surface::reconstructNormals | ( | NormalTransform | xform, |
TimingContext * | tc = 0 ) |
Reconstructs 3D normals from 2D transformed normals.
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.
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.
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.
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.
NVTT_API bool nvtt::Surface::save | ( | const char * | fileName, |
bool | hasAlpha = false, | ||
bool | hdr = false, | ||
TimingContext * | tc = 0 ) const |
Saves texture data to file.
true
if saving succeeded and false
if it failed.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. |
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
.
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.
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.
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.
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.
true
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.
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.
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.
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.
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.
NVTT_API void nvtt::Surface::toGamma | ( | int | channel, |
float | gamma, | ||
TimingContext * | tc = 0 ) |
Raises the given channel to the power 1/gamma
.
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.
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
and then all channels (including alpha) are set to grey
.
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.
NVTT_API void nvtt::Surface::toLinear | ( | int | channel, |
float | gamma, | ||
TimingContext * | tc = 0 ) |
Raises the given channel to the power gamma
.
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
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
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
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)
.
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))
.
NVTT_API void nvtt::Surface::toneMap | ( | ToneMapper | tm, |
float * | parameters, | ||
TimingContext * | tc = 0 ) |
Applies an HDR-to-LDR tone mapper.
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].
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.
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.
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
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
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
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
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
NVTT_API void nvtt::Surface::transformNormals | ( | NormalTransform | xform, |
TimingContext * | tc = 0 ) |
Applies a 3D->2D normal transformation, setting the z (blue) channel to 0.