AuroraMiddleware/DirectXTex
1
0
Fork 0
mirror of https://github.com/microsoft/DirectXTex synced 2024-11-21 12:00:06 +00:00
Code Issues Releases Wiki Activity

Reformat

Chuck Walbourn 2018-12-03 12:36:55 -08:00
parent 4921c6050d
commit c72d0dc762
33 changed files with 1013 additions and 804 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
Adding-OpenEXR.md

@ -1,7 +1,5 @@
The [OpenEXR](https://en.wikipedia.org/wiki/OpenEXR) format is a high dynamic-range (HDR) image file format developed by Industrial Light & Magic for use in computer imaging applications. It is commonly used as a source format for HDR textures.
_Be sure to note that the OpenEXR library has it's own [license terms](http://www.openexr.com/license.html), as does the required [ZLIB library](http://www.zlib.net/zlib_license.html)._
# Building the OpenEXR auxiliary library
The OpenEXR library can be obtained from [GitHub](https://github.com/openexr/openexr). Building the library requires [CMake](https://cmake.org/download/) and [ZLib](http://www.zlib.net).
@ -33,27 +31,30 @@ The OpenEXR package [x86](https://www.nuget.org/packages/openexr-msvc-x86/) or [
Note that OpenEXR is subject to its own [license](https://github.com/openexr/openexr/blob/develop/OpenEXR/LICENSE) as is [zlib](http://zlib.net/zlib_license.html).
# Functions
## GetMetadataFromEXRFile
Returns the _TexMetadata_ from a ``.EXR`` file.
HRESULT GetMetadataFromEXRFile( const wchar_t* szFile,
TexMetadata& metadata );
```cpp
HRESULT GetMetadataFromEXRFile( wchar_t* szFile, TexMetadata& metadata );
```
## LoadFromEXRFile
Loads a ``.EXR`` file.
HRESULT LoadFromEXRFile const wchar_t* szFile,
TexMetadata* metadata, ScratchImage& image );
```cpp
HRESULT LoadFromEXRFile( const wchar_t* szFile, TexMetadata* metadata, ScratchImage& image );
```
* The data is always loaded as ``R16G16B16A16_FLOAT``.
## SaveToEXRFile
Saves a single image to a ``.EXR`` file.
HRESULT SaveToEXRFile( const Image& image, const wchar_t* szFile );
```cpp
HRESULT SaveToEXRFile( const Image& image, const wchar_t* szFile );
```
* ``R16G16B16A16_FLOAT``, ``R32G32B32A32_FLOAT``, and ``R32G32B32_FLOAT`` data are supported for writing, and are always written as ``half`` channel format data.
@ -64,33 +65,39 @@ For the load functions, the _metadata_ parameter can be nullptr as this informat
This is a simple loading example.
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromEXRFile( L"flowers.exr", nullptr, *image );
if ( FAILED(hr) )
// error
```cpp
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromEXRFile( L"flowers.exr", nullptr, *image );
if ( FAILED(hr) )
// error
```
Storing an image.
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToEXRFile( *img, L"NEW_IMAGE.EXR" );
if ( FAILED(hr) )
// error
```cpp
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToEXRFile( *img, L"NEW_IMAGE.EXR" );
if ( FAILED(hr) )
// error
```
You can also save data directly from memory without using the intermediate **ScratchImage** at all. This example assumes a single 2D image is being written out.
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /* DXGI_FORMAT_R16G16B16A16_FLOAT,
DXGI_FORMAT_R32G32B32A32_FLOAT
or DXGI_FORMAT_R32G32B32_FLOAT */;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToEXRFile( img, L"NEW_IMAGE.EXR" );
if ( FAILED(hr) )
// error
```cpp
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /* DXGI_FORMAT_R16G16B16A16_FLOAT,
DXGI_FORMAT_R32G32B32A32_FLOAT
or DXGI_FORMAT_R32G32B32_FLOAT */;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToEXRFile( img, L"NEW_IMAGE.EXR" );
if ( FAILED(hr) )
// error
```
# Samples
@ -101,8 +108,8 @@ Sample images can be obtained from [GitHub](https://github.com/openexr/openexr-i
The tools that use DirectXTex can be updated to opt-in to OpenEXR support as well, typically by enabling ``#define USE_OPENEXR`` and rebuilding. See [[texconv]], [[texdiag]], [[texassemble]], and [uvatlastool](https://github.com/Microsoft/UVAtlas/wiki/UVAtlasTool).
# Further reading
[OpenEXR](http://www.openexr.com/)
[OpenEXR](http://www.openexr.com/)
Kainz, Bogart, and Hess. "Chapter 26. The OpenEXR Image File Format", _GPU Gems_, Addison-Wesley, 2004 [link](http://http.developer.nvidia.com/GPUGems/gpugems_ch26.html)
[High Dynamic Range Image Encodings](http://www.anyhere.com/gward/hdrenc/hdr_encodings.html)
[High Dynamic Range Image Encodings](http://www.anyhere.com/gward/hdrenc/hdr_encodings.html)

44
CaptureTexture.md

@ -1,28 +1,36 @@
Captures a Direct3D render target and returns an image.
_This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using ScreenGrab [DX11](https://github.com/Microsoft/DirectXTK/wiki/ScreenGrab) / [DX12](https://github.com/Microsoft/DirectXTK12/wiki/ScreenGrab) instead of DirectXTex._
> This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using ScreenGrab [DX11](https://github.com/Microsoft/DirectXTK/wiki/ScreenGrab) / [DX12](https://github.com/Microsoft/DirectXTK12/wiki/ScreenGrab) instead of DirectXTex.
HRESULT CaptureTexture( ID3D11Device* pDevice, ID3D11DeviceContext* pContext,
ID3D11Resource* pSource,
ScratchImage& result );
```cpp
HRESULT CaptureTexture(
ID3D11Device* pDevice, ID3D11DeviceContext* pContext,
ID3D11Resource* pSource,
ScratchImage& result );
HRESULT CaptureTexture( ID3D12CommandQueue* pCommandQueue, ID3D12Resource* pSource,
bool isCubeMap,
ScratchImage& result,
D3D12_RESOURCE_STATES beforeState = D3D12_RESOURCE_STATE_RENDER_TARGET,
D3D12_RESOURCE_STATES afterState = D3D12_RESOURCE_STATE_RENDER_TARGET );
HRESULT CaptureTexture(
ID3D12CommandQueue* pCommandQueue,
ID3D12Resource* pSource,
bool isCubeMap,
ScratchImage& result,
D3D12_RESOURCE_STATES beforeState = D3D12_RESOURCE_STATE_RENDER_TARGET,
D3D12_RESOURCE_STATES afterState = D3D12_RESOURCE_STATE_RENDER_TARGET );
```
# Example
ScratchImage image;
HRESULT hr = CaptureTexture( device, context, pResource, image );
if ( SUCCEEDED(hr) )
```cpp
ScratchImage image;
HRESULT hr = CaptureTexture( device, context, pResource, image );
if ( SUCCEEDED(hr) )
{
hr = SaveToDDSFile( image.GetImages(),
image.GetImageCount(), image.GetMetadata(),
DDS_FLAGS_NONE, filename );
if ( FAILED(hr) )
{
hr = SaveToDDSFile( image.GetImages(), image.GetImageCount(), image.GetMetadata(),
DDS_FLAGS_NONE, filename );
if ( FAILED(hr) )
{
...
...
```
# Remarks
@ -32,4 +40,4 @@ MSAA textures are resolved before being captured.
> If support for DirectX 12 is required, you must explicitly include ``#include <d3d12.h>`` before including ``#include "DirectXTex.h"``
DirectX 12 version does not support capturing textures from depth/stencil planar formats.
DirectX 12 version does not support capturing textures from depth/stencil planar formats.

72
Compress.md

@ -1,23 +1,31 @@
Compresses an image or set of images to a block-compressed (BC) format.
Compresses an image or set of images to a block-compressed (BC) format.
HRESULT Compress( const Image& srcImage, DXGI_FORMAT format,
DWORD compress, float threshold,
ScratchImage& cImage );
## CPU Codec
```cpp
HRESULT Compress( const Image& srcImage, DXGI_FORMAT format,
DWORD compress, float threshold,
ScratchImage& cImage );
HRESULT Compress( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, DWORD compress, float threshold,
ScratchImage& cImages );
HRESULT Compress( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, DWORD compress, float threshold,
ScratchImage& cImages );
```
HRESULT Compress( ID3D11Device* pDevice, const Image& srcImage,
DXGI_FORMAT format, DWORD compress, float alphaWeight,
ScratchImage& image );
## GPU Codec (BC6H/BC7)
```cpp
HRESULT Compress( ID3D11Device* pDevice, const Image& srcImage,
DXGI_FORMAT format, DWORD compress, float alphaWeight,
ScratchImage& image );
HRESULT Compress( ID3D11Device* pDevice,
const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, DWORD compress, float alphaWeight,
ScratchImage& cImages );
HRESULT Compress( ID3D11Device* pDevice,
const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, DWORD compress, float alphaWeight,
ScratchImage& cImages );
```
> GPU compression is not yet supported for DirectX 12 devices.
# Parameters
@ -39,7 +47,7 @@ _alphaWeight_: Used to weight the error metric's alpha computation for the BC7 G
## Dithering
* ``TEX_COMPRESS_RGB_DITHER`` Enables dithering RGB colors for BC1-3 compression
* ``TEX_COMPRESS_A_DITHER`` Enables dithering alpha channel for BC1-3 compression
* ``TEX_COMPRESS_DITHER`` Same as ``TEX_COMPRESS_RGB_DITHER`` and ``TEX_COMPRESS_A_DITHER``
* ``TEX_COMPRESS_DITHER`` Same as ``TEX_COMPRESS_RGB_DITHER`` and ``TEX_COMPRESS_A_DITHER``
## Weighting
* ``TEX_COMPRESS_UNIFORM`` By default, BC1-3 uses a perceptual weighting. By using this flag, the perceptual weighting is disabled which can be useful when using the RGB channels for other data.
@ -50,7 +58,7 @@ _alphaWeight_: Used to weight the error metric's alpha computation for the BC7 G
## Color space
* ``TEX_COMPRESS_SRGB_IN`` Indicates the input format is the sRGB format. This is implied if using a ``DXGI_FORMAT_*_SRGB`` format
* ``TEX_COMPRESS_SRGB_OUT`` Indicates the output format is the sRGB format. This is implied if using a ``DXGI_FORMAT_*_SRGB`` format
* ``TEX_COMPRESS_SRGB`` This is the same as setting both ``TEX_COMPRESS_SRGB_IN`` and ``TEX_COMPRESS_SRGB_OUT``
* ``TEX_COMPRESS_SRGB`` This is the same as setting both ``TEX_COMPRESS_SRGB_IN`` and ``TEX_COMPRESS_SRGB_OUT``
_The [sRGB color space](http://en.wikipedia.org/wiki/SRGB) overall is approximately equivalent to gamma 2.2. It's actually linear below a threshold, and gamma 2.4 beyond that._
@ -61,17 +69,19 @@ _The [sRGB color space](http://en.wikipedia.org/wiki/SRGB) overall is approximat
# Example
ScratchImage srcImage;
```cpp
ScratchImage srcImage;
...
ScratchImage bcImage;
hr = Compress( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(), DXGI_FORMAT_BC3_UNORM,
TEX_COMPRESS_DEFAULT, TEX_THRESHOLD_DEFAULT,
bcImage );
if ( FAILED(hr) )
...
ScratchImage bcImage;
hr = Compress( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(), DXGI_FORMAT_BC3_UNORM,
TEX_COMPRESS_DEFAULT, TEX_THRESHOLD_DEFAULT,
bcImage );
if ( FAILED(hr) )
...
```
# Remarks
@ -85,7 +95,7 @@ This function cannot operate directly on a planar format image. See [[ConvertToS
# Release Notes
The software based encoder for BC6H and BC7 is computationally expensive and can be quite slow. The DirectCompute based encoder which is much faster has been integrated into the DirectXTex library, but the standalone version is also available on [MSDN Code Gallery](http://code.msdn.microsoft.com/BC6HBC7-DirectCompute-35e8884a).
The software based encoder for BC6H and BC7 is computationally expensive and can be quite slow. The DirectCompute based encoder which is much faster has been integrated into the DirectXTex library, but the standalone version is also available on [GitHub](https://github.com/walbourn/directx-sdk-samples/tree/master/BC6HBC7EncoderCS).
# Threading
@ -95,9 +105,9 @@ The DirectCompute GPU-based compressor makes use of the device's immediate conte
# Related Links
[Compressed Texture Resources (Direct3D 9)](http://msdn.microsoft.com/en-us/library/bb204843.aspx)
[Block Compression (Direct3D 10)](http://msdn.microsoft.com/en-us/library/bb694531.aspx])
[Texture Block Compression in Direct3D 11](http://msdn.microsoft.com/en-us/library/windows/desktop/hh308955.aspx)
[Compressed Texture Resources (Direct3D 9)](https://docs.microsoft.com/en-us/windows/desktop/direct3d9/compressed-texture-resources)
[Block Compression (Direct3D 10)](https://docs.microsoft.com/en-us/windows/desktop/direct3d10/d3d10-graphics-programming-guide-resources-block-compression)
[Texture Block Compression in Direct3D 11](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/texture-block-compression-in-direct3d-11)
[S3 Texture Compress](http://en.wikipedia.org/wiki/S3_Texture_Compression)
[3Dc](http://en.wikipedia.org/wiki/3Dc)
[OpenGL ARB BPTC](http://developer.download.nvidia.com/opengl/specs/GL_ARB_texture_compression_bptc.txt)

9
ComputeMSE.md

@ -1,8 +1,11 @@
Computes the mean-squared error for each component based on two input images.
HRESULT ComputeMSE( const Image& image1, const Image& image2,
float& mse, float* mseV,
DWORD flags = 0 );
```cpp
HRESULT ComputeMSE(
const Image& image1, const Image& image2,
float& mse, float* mseV,
DWORD flags = 0 );
```
# Parameters

36
ComputeNormalMap.md

@ -1,13 +1,17 @@
Converts a height-map to a normal-map.
HRESULT ComputeNormalMap( const Image& srcImage, DWORD flags,
float amplitude, DXGI_FORMAT format,
ScratchImage& normalMap );
```cpp
HRESULT ComputeNormalMap(
const Image& srcImage, DWORD flags,
float amplitude, DXGI_FORMAT format,
ScratchImage& normalMap );
HRESULT ComputeNormalMap( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DWORD flags, float amplitude, DXGI_FORMAT format,
ScratchImage& normalMaps );
HRESULT ComputeNormalMap(
const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DWORD flags, float amplitude, DXGI_FORMAT format,
ScratchImage& normalMaps );
```
# Parameters
@ -36,16 +40,18 @@ _format_: Format of the resulting ScratchImage
# Example
ScratchImage hmapImage;
```cpp
ScratchImage hmapImage;
...
ScratchImage normalMap;
hr = ComputeNormalMap( hmapImage.GetImage(0,0,0),
CNMAP_CHANNEL_LUMINANCE | CNMAP_COMPUTE_OCCLUSION,
2.f, DXGI_FORMAT_R8G8B8A8_UNORM, normalMap );
if ( FAILED(hr) )
...
ScratchImage normalMap;
hr = ComputeNormalMap( hmapImage.GetImage(0,0,0),
CNMAP_CHANNEL_LUMINANCE | CNMAP_COMPUTE_OCCLUSION,
2.f, DXGI_FORMAT_R8G8B8A8_UNORM, normalMap );
if ( FAILED(hr) )
...
```
# Remarks
This function does not operate directly on block compressed images. See [[Decompress]] and [[Compress]].

9
ComputePitch.md

@ -1,7 +1,10 @@
Returns both the row and slice pitch for a given width, height, and DXGI format. It supports a number of flags for overriding the default byte-alignment usually used by ``DDS`` files and Direct3D resources.
HRESULT ComputePitch( DXGI_FORMAT fmt, size_t width, size_t height,
size_t& rowPitch, size_t& slicePitch, DWORD flags = CP_FLAGS_NONE );
```cpp
HRESULT ComputePitch(
DXGI_FORMAT fmt, size_t width, size_t height,
size_t& rowPitch, size_t& slicePitch, DWORD flags = CP_FLAGS_NONE );
```
# Parameters
@ -39,4 +42,4 @@ In most cases the function returns ``S_OK`` and valid output parameters ``rowPit
If the input DXGI format is unknown, then it can return ``E_INVALIDARG``, which only happens if ``BitsPerPixel`` returns 0.
In 32-bit builds, the function will return ``HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW)`` if either of the computed pitch values exceed the range of ``size_t``.
In 32-bit builds, the function will return ``HRESULT_FROM_WIN32(ERROR_ARITHMETIC_OVERFLOW)`` if either of the computed pitch values exceed the range of ``size_t``.

6
ComputeScanlines.md

@ -1,7 +1,9 @@
Returns the number of horizontal scanlines in an image given the DXGI format and pixel height.
size_t ComputeScanlines( DXGI_FORMAT fmt, size_t height );
```cpp
size_t ComputeScanlines( DXGI_FORMAT fmt, size_t height );
```
# Remarks
For most images, the number of scanlines is the same as the height of the image. For block-compressed (BC) images, the number of scanlines is 1/4 of the original height since each scanline contains 4x4 blocks. For planar images, this number can be 1.5x or 2x the original height.
For most images, the number of scanlines is the same as the height of the image. For block-compressed (BC) images, the number of scanlines is 1/4 of the original height since each scanline contains 4x4 blocks. For planar images, this number can be 1.5x or 2x the original height.

40
Convert.md

@ -1,13 +1,17 @@
Convert an image or set of images from one pixel format to another.
HRESULT Convert( const Image& srcImage,
DXGI_FORMAT format, DWORD filter,
float threshold, ScratchImage& image );
```cpp
HRESULT Convert(
const Image& srcImage,
DXGI_FORMAT format, DWORD filter,
float threshold, ScratchImage& image );
HRESULT Convert( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, DWORD filter,
float threshold, ScratchImage& result );
HRESULT Convert(
const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, DWORD filter,
float threshold, ScratchImage& result );
```
# Parameters
@ -19,17 +23,19 @@ _threshold_: Alpha threshold used for converting to single bit alpha channels (0
# Example
ScratchImage srcImage;
```cpp
ScratchImage srcImage;
...
ScratchImage destImage;
hr = Convert( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(),
DXGI_FORMAT_R8G8B8A8_UNORM, TEX_FILTER_DEFAULT, TEX_THRESHOLD_DEFAULT,
destImage );
if ( FAILED(hr) )
...
ScratchImage destImage;
hr = Convert( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(),
DXGI_FORMAT_R8G8B8A8_UNORM, TEX_FILTER_DEFAULT, TEX_THRESHOLD_DEFAULT,
destImage );
if ( FAILED(hr) )
...
```
# Remarks
@ -37,4 +43,4 @@ This function does not operate directly on block compressed images. See [[Decomp
This function cannot operate directly on a planar format image. See [[ConvertToSinglePlane]] for a method for converting planar data to a format that is supported by this routine.
This function is implemented with both WIC and non-WIC code paths. The non-WIC paths is generally used when the standard WIC conversion behavior is unintuitive for textures or would modify the color space in unexpected ways.
This function is implemented with both WIC and non-WIC code paths. The non-WIC paths is generally used when the standard WIC conversion behavior is unintuitive for textures or would modify the color space in unexpected ways.

18
ConvertToSinglePlane.md

@ -1,14 +1,18 @@
Converts a planar image (such as 4:2:0 or 4:1:1 video format) to a non-planar format (typically 4:2:2 for video formats). Planar formats are not supported by other texture functions, so this routine can be used to convert planar data to a form that other functions will operate on.
HRESULT ConvertToSinglePlane( const Image& srcImage,
ScratchImage& image );
```cpp
HRESULT ConvertToSinglePlane(
const Image& srcImage,
ScratchImage& image );
HRESULT ConvertToSinglePlane( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
ScratchImage& image );
HRESULT ConvertToSinglePlane(
const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
ScratchImage& image );
```
# Remarks
The pixel format of the resulting image is determined by the format of the input. For example NV11 and NV12 are always converted to YUY2.
[Recommended 8-Bit YUV Formats for Video Rendering](http://msdn.microsoft.com/en-us/library/windows/desktop/dd206750.aspx)
[10-bit and 16-bit YUV Video Formats](http://msdn.microsoft.com/en-us/library/windows/desktop/bb970578.aspx)
[Recommended 8-Bit YUV Formats for Video Rendering](https://docs.microsoft.com/en-us/windows/desktop/medfound/recommended-8-bit-yuv-formats-for-video-rendering)
[10-bit and 16-bit YUV Video Formats](https://docs.microsoft.com/en-us/windows/desktop/medfound/10-bit-and-16-bit-yuv-video-formats)

34
CopyRectangle.md

@ -1,8 +1,11 @@
Copies a rectangle of pixels from one image to another.
HRESULT CopyRectangle( const Image& srcImage, const Rect& srcRect,
const Image& dstImage,
DWORD filter, size_t xOffset, size_t yOffset );
```cpp
HRESULT CopyRectangle(
const Image& srcImage, const Rect& srcRect,
const Image& dstImage,
DWORD filter, size_t xOffset, size_t yOffset );
```
# Parameters
@ -16,19 +19,21 @@ _xOffset_, _yOffset_: Pixel location of destination rectangle in _dstImage_. The
Here's an example that copies a source image to the location (100,50) location in a new, larger image.
ScratchImage srcImage;
```cpp
ScratchImage srcImage;
...
ScratchImage destImage;
destImage.Iniitalize2D( ... );
auto mdata = srcImage.GetMetadata();
Rect r( 0, 0, mdata.width, mdata.height );
hr = CopyRectangle( *srcImage.GetImage(0,0,0), r, *dstImage.GetImage(0,0,0),
TEX_FILTER_DEFAULT, 100, 50 );
if ( FAILED(hr) )
...
ScratchImage destImage;
destImage.Iniitalize2D( ... );
auto mdata = srcImage.GetMetadata();
Rect r( 0, 0, mdata.width, mdata.height );
hr = CopyRectangle( *srcImage.GetImage(0,0,0), r, *dstImage.GetImage(0,0,0),
TEX_FILTER_DEFAULT, 100, 50 );
if ( FAILED(hr) )
...
```
# Remarks
@ -37,4 +42,3 @@ Behavior of this function is not defined if the source and destination image are
Block compressed images are not supported as either the source or destination. Use [[Decompress]] to uncompress BC images before using this function.
This function cannot operate directly on a planar format image. See [[ConvertToSinglePlane]] for a method for converting planar data to a format that is supported by this routine.

84
CreateShaderResourceView.md

@ -1,18 +1,22 @@
Creates a Direct3D 11 resource and shader resource view from a set of images.
_This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using [DDSTextureLoader](https://github.com/Microsoft/DirectXTK/wiki/DDSTextureLoader), and/or [WICTextureLoader](https://github.com/Microsoft/DirectXTK/wiki/WICTextureLoader) instead of DirectXTex._
> This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using [DDSTextureLoader](https://github.com/Microsoft/DirectXTK/wiki/DDSTextureLoader), and/or [WICTextureLoader](https://github.com/Microsoft/DirectXTK/wiki/WICTextureLoader) instead of DirectXTex.
HRESULT CreateShaderResourceView( ID3D11Device* pDevice,
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
ID3D11ShaderResourceView** ppSRV );
```cpp
HRESULT CreateShaderResourceView(
ID3D11Device* pDevice,
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
ID3D11ShaderResourceView** ppSRV );
HRESULT CreateShaderResourceViewEx( ID3D11Device* pDevice,
const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
D3D11_USAGE usage, unsigned int bindFlags,
unsigned int cpuAccessFlags, unsigned int miscFlags,
bool forceSRGB,
ID3D11ShaderResourceView** ppSRV );
HRESULT CreateShaderResourceViewEx(
ID3D11Device* pDevice,
const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
D3D11_USAGE usage, unsigned int bindFlags,
unsigned int cpuAccessFlags, unsigned int miscFlags,
bool forceSRGB,
ID3D11ShaderResourceView** ppSRV );
```
# Parameters
@ -28,36 +32,38 @@ _This function is intended for use with tools or editor programs. For runtime/en
# Example
wchar_t ext[_MAX_EXT];
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );
```cpp
wchar_t ext[_MAX_EXT] = {};
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, nullptr, image );
}
else if ( _wcsicmp( ext, L".tga" ) == 0 )
{
hr = LoadFromTGAFile( filename, nullptr, image );
}
else if ( _wcsicmp( ext, L".hdr" ) == 0 )
{
hr = LoadFromHDRFile( filename, nullptr, image );
}
else
{
hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, nullptr, image );
}
if ( SUCCEEDED(hr) )
{
ID3D11ShaderResourceView* * pSRV = nullptr;
hr = CreateShaderResourceView( device,
image.GetImages(), image.GetImageCount(),
image.GetMetadata(), &pSRV );
if ( FAILED(hr) )
{
hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, nullptr, image );
}
else if ( _wcsicmp( ext, L".tga" ) == 0 )
{
hr = LoadFromTGAFile( filename, nullptr, image );
}
else if ( _wcsicmp( ext, L".hdr" ) == 0 )
{
hr = LoadFromHDRFile( filename, nullptr, image );
}
else
{
hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, nullptr, image );
}
if ( SUCCEEDED(hr) )
{
ID3D11ShaderResourceView* * pSRV = nullptr;
hr = CreateShaderResourceView( device,
image.GetImages(), image.GetImageCount(),
image.GetMetadata(), &pSRV );
if ( FAILED(hr) )
{
...
...
```
# Remark

166
CreateTexture.md

@ -1,31 +1,40 @@
Creates a Direct3D resource from a set of images.
_This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using DDSTextureLoader [DX11](https://github.com/Microsoft/DirectXTK/wiki/DDSTextureLoader) / [DX12](https://github.com/Microsoft/DirectXTK12/wiki/DDSTextureLoader), and/or WICTextureLoader [DX11](https://github.com/Microsoft/DirectXTK/wiki/WICTextureLoader) / [DX12](https://github.com/Microsoft/DirectXTK12/wiki/WICTextureLoader) instead of DirectXTex._
> This function is intended for use with tools or editor programs. For runtime/engine use, we strongly recommend using DDSTextureLoader [DX11](https://github.com/Microsoft/DirectXTK/wiki/DDSTextureLoader) / [DX12](https://github.com/Microsoft/DirectXTK12/wiki/DDSTextureLoader), and/or WICTextureLoader [DX11](https://github.com/Microsoft/DirectXTK/wiki/WICTextureLoader) / [DX12](https://github.com/Microsoft/DirectXTK12/wiki/WICTextureLoader) instead of DirectXTex.
## DirectX 11
HRESULT CreateTexture( ID3D11Device* pDevice,
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
ID3D11Resource** ppResource );
```cpp
HRESULT CreateTexture(
ID3D11Device* pDevice,
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
ID3D11Resource** ppResource );
HRESULT CreateTextureEx( ID3D11Device* pDevice,
const Image* srcImages, _In_ size_t nimages, const TexMetadata& metadata,
D3D11_USAGE usage, unsigned int bindFlags,
unsigned int cpuAccessFlags, unsigned int miscFlags,
bool forceSRGB,
ID3D11Resource** ppResource );
HRESULT CreateTextureEx(
ID3D11Device* pDevice,
const Image* srcImages, _In_ size_t nimages, const TexMetadata& metadata,
D3D11_USAGE usage, unsigned int bindFlags,
unsigned int cpuAccessFlags, unsigned int miscFlags,
bool forceSRGB,
ID3D11Resource** ppResource );
```
## DirectX 12
HRESULT CreateTexture( ID3D12Device* pDevice, const TexMetadata& metadata,
ID3D12Resource** ppResource );
```cpp
HRESULT CreateTexture(
ID3D12Device* pDevice, const TexMetadata& metadata,
ID3D12Resource** ppResource );
HRESULT CreateTextureEx( ID3D12Device* pDevice, const TexMetadata& metadata,
D3D12_RESOURCE_FLAGS resFlags, bool forceSRGB,
ID3D12Resource** ppResource );
HRESULT CreateTextureEx(
ID3D12Device* pDevice, const TexMetadata& metadata,
D3D12_RESOURCE_FLAGS resFlags, bool forceSRGB,
ID3D12Resource** ppResource );
HRESULT PrepareUpload( ID3D12Device* pDevice,
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
std::vector<D3D12_SUBRESOURCE_DATA>& subresources );
HRESULT PrepareUpload(
ID3D12Device* pDevice,
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
std::vector<D3D12_SUBRESOURCE_DATA>& subresources );
```
# Parameters
@ -41,73 +50,79 @@ _This function is intended for use with tools or editor programs. For runtime/en
# Example
wchar_t ext[_MAX_EXT];
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );
```cpp
wchar_t ext[_MAX_EXT] = {};
_wsplitpath_s( filename, nullptr, 0, nullptr, 0, nullptr, 0, ext, _MAX_EXT );
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, nullptr, image );
}
else if ( _wcsicmp( ext, L".tga" ) == 0 )
{
hr = LoadFromTGAFile( filename, nullptr, image );
}
else if ( _wcsicmp( ext, L".hdr" ) == 0 )
{
hr = LoadFromHDRFile( filename, nullptr, image );
}
else
{
hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, nullptr, image );
}
...
ScratchImage image;
HRESULT hr;
if ( _wcsicmp( ext, L".dds" ) == 0 )
{
hr = LoadFromDDSFile( filename, DDS_FLAGS_NONE, nullptr, image );
}
else if ( _wcsicmp( ext, L".tga" ) == 0 )
{
hr = LoadFromTGAFile( filename, nullptr, image );
}
else if ( _wcsicmp( ext, L".hdr" ) == 0 )
{
hr = LoadFromHDRFile( filename, nullptr, image );
}
else
{
hr = LoadFromWICFile( filename, WIC_FLAGS_NONE, nullptr, image );
}
...
```
## DirectX 11
if ( SUCCEEDED(hr) )
{
ID3D11Resource* pResource = nullptr;
hr = CreateTexture( device,
image.GetImages(), image.GetImageCount(),
image.GetMetadata(), &pResource );
if ( FAILED(hr) )
// error!
```cpp
if ( SUCCEEDED(hr) )
{
ID3D11Resource* pResource = nullptr;
hr = CreateTexture( device,
image.GetImages(), image.GetImageCount(),
image.GetMetadata(), &pResource );
if ( FAILED(hr) )
// error!
```
## DirectX 12
if ( SUCCEEDED(hr) )
{
ID3D12Resource* pResource = nullptr;
hr = CreateTexture( device, image.GetMetadata(), &pResource );
if ( FAILED(hr) )
// error!
```cpp
if ( SUCCEEDED(hr) )
{
ID3D12Resource* pResource = nullptr;
hr = CreateTexture( device, image.GetMetadata(), &pResource );
if ( FAILED(hr) )
// error!
std::vector<D3D12_SUBRESOURCE_DATA> subresources;
hr = PrepareUpload( device, image.GetImages(), image.GetImageCount(), metadata,
subresources );
if ( FAILED(hr) )
// error!
std::vector<D3D12_SUBRESOURCE_DATA> subresources;
hr = PrepareUpload( device, image.GetImages(), image.GetImageCount(), metadata,
subresources );
if ( FAILED(hr) )
// error!
// upload is implemented by application developer. Here's one solution using <d3dx12.h>
const UINT64 uploadBufferSize = GetRequiredIntermediateSize(pResource,
0, static_cast<unsigned int>(subresources.size()));
// upload is implemented by application developer. Here's one solution using <d3dx12.h>
const UINT64 uploadBufferSize = GetRequiredIntermediateSize(pResource,
0, static_cast<unsigned int>(subresources.size()));
ComPtr<ID3D12Resource> textureUploadHeap;
hr = device->CreateCommittedResource(
&CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_UPLOAD),
D3D12_HEAP_FLAG_NONE,
&CD3DX12_RESOURCE_DESC::Buffer(uploadBufferSize),
D3D12_RESOURCE_STATE_GENERIC_READ,
nullptr,
IID_PPV_ARGS(textureUploadHeap.GetAddressOf()));
if (FAILED(hr))
// error!
ComPtr<ID3D12Resource> textureUploadHeap;
hr = device->CreateCommittedResource(
&CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_UPLOAD),
D3D12_HEAP_FLAG_NONE,
&CD3DX12_RESOURCE_DESC::Buffer(uploadBufferSize),
D3D12_RESOURCE_STATE_GENERIC_READ,
nullptr,
IID_PPV_ARGS(textureUploadHeap.GetAddressOf()));
if (FAILED(hr))
// error!
UpdateSubresources(commandList,
pResource, textureUploadHeap.Get(),
0, 0, static_cast<unsigned int>(subresources.size()),
subresources.data());
UpdateSubresources(commandList,
pResource, textureUploadHeap.Get(),
0, 0, static_cast<unsigned int>(subresources.size()),
subresources.data());
```
Note the data is copied out of the ``image`` into the UPLOAD resource by the time the ``UpdateSubresources`` returns. The upload resource itself needs to remain live until after the command-list is processed, and the texture won't be ready to use until then.
@ -122,4 +137,3 @@ This function does not provide support for auto-gen mipmaps (the runtime/engine
> If support for DirectX 12 is required, you must explicitly include ``#include <d3d12.h>`` before including ``#include "DirectXTex.h"``
DirectX 12 version does not support creating textures from depth/stencil non-planar data.

144
DDS-I-O-Functions.md

@ -1,37 +1,43 @@
These functions perform file I/O for ``.DDS`` files. These functions support many legacy Direct3D 9 ``.DDS`` files and all Direct3D 10.x/11.x era "DX10" extension ``.DDS`` files
# GetMetadataFromDDSMemory, GetMetadataFromDDSFile
Returns the _TexMetadata_ from a ``.DDS`` file.
Returns the _TexMetadata_ structure from a ``.DDS`` file.
HRESULT GetMetadataFromDDSMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata& metadata );
```cpp
HRESULT GetMetadataFromDDSMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata& metadata );
HRESULT GetMetadataFromDDSFile( const wchar_t* szFile,
DWORD flags, TexMetadata& metadata );
HRESULT GetMetadataFromDDSFile( const wchar_t* szFile,
DWORD flags, TexMetadata& metadata );
```
#LoadFromDDSMemory, LoadFromDDSFile
Loads a ``.DDS`` file.
# LoadFromDDSMemory, LoadFromDDSFile
Loads a ``.DDS`` file (including performing any necessary legacy conversions).
HRESULT LoadFromDDSMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata* metadata, ScratchImage& image );
```cpp
HRESULT LoadFromDDSMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata* metadata, ScratchImage& image );
HRESULT LoadFromDDSFile( _In_z_ const wchar_t* szFile,
DWORD flags, TexMetadata* metadata, ScratchImage& image );
HRESULT LoadFromDDSFile( _In_z_ const wchar_t* szFile,
DWORD flags, TexMetadata* metadata, ScratchImage& image );
```
# SaveToDDSMemory, SaveToDDSFile
Saves a single image or a set of images to a ``.DDS`` file.
HRESULT SaveToDDSMemory( const Image& image, DWORD flags,
Blob& blob );
```cpp
HRESULT SaveToDDSMemory( const Image& image, DWORD flags,
Blob& blob );
HRESULT SaveToDDSMemory( const Image* images, size_t nimages,
const TexMetadata& metadata, DWORD flags, Blob& blob );
HRESULT SaveToDDSMemory( const Image* images, size_t nimages,
const TexMetadata& metadata, DWORD flags, Blob& blob );
HRESULT SaveToDDSFile( const Image& image, DWORD flags,
const wchar_t* szFile );
HRESULT SaveToDDSFile( const Image& image, DWORD flags,
const wchar_t* szFile );
HRESULT SaveToDDSFile( const Image* images, size_t nimages,
const TexMetadata& metadata, DWORD flags, const wchar_t* szFile );
HRESULT SaveToDDSFile( const Image* images, size_t nimages,
const TexMetadata& metadata, DWORD flags, const wchar_t* szFile );
```
# Parameters
For the load functions, the _metadata_ parameter can be nullptr as this information is also available in the returned **ScratchImage**.
@ -39,37 +45,43 @@ For the load functions, the _metadata_ parameter can be nullptr as this informat
# Examples
This is a simple loading example. A ``DDS`` file can potentially include any kind of Direct3D resource in any DXGI format, so the _TexMetadata_ info is needed to understand the full content of the file.
TexMetadata info;
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromDDSFile( L"TEXTURE.DDS",
DDS_FLAGS_NONE, &info, *image );
if ( FAILED(hr) )
// error
```cpp
TexMetadata info;
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromDDSFile( L"TEXTURE.DDS",
DDS_FLAGS_NONE, &info, *image );
if ( FAILED(hr) )
// error
```
When saving a ``DDS`` file, it can contain one or more images (mipmaps, arrays, volumes, cubemaps, etc.).
When saving a ``DDS`` file, it can contain one or more images (mipmaps, arrays, volumes, cubemaps, etc.).
Therefore, the writer needs the _TexMetadata_ info to know how to interpret the image set.
const Image* img = image->GetImages();
assert( img );
size_t nimg = image->GetImageCount();
assert( nimg > 0 );
HRESULT hr = SaveToDDSFile( img, nimg, image->GetMetadata(),
DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
// error
```cpp
const Image* img = image->GetImages();
assert( img );
size_t nimg = image->GetImageCount();
assert( nimg > 0 );
HRESULT hr = SaveToDDSFile( img, nimg, image->GetMetadata(),
DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
// error
```
You can also save data directly from memory without using the intermediate **ScratchImage** at all. This example assumes a single 2D image is being written out.
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<any DXGI format>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToDDSFile( img, DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
// error
```cpp
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<any DXGI format>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToDDSFile( img, DDS_FLAGS_NONE, L"NEW_TEXTURE.DDS" );
if ( FAILED(hr) )
// error
```
# Related Flags
* ``DDS_FLAGS_NONE`` is the default
@ -95,45 +107,53 @@ You can also save data directly from memory without using the intermediate **Scr
# Remarks
Many older Direct3D 9 formats that do not directly map to DXGI formats are converted at load-time. For example, ``D3DFMT_R8G8B8`` is always converted to ``DXGI_FORMAT_R8G8B8A8_UNORM`` since there is no 24bpp DXGI format.
The 'DX10' header is not supported by D3DX9, older Direct3D 9 era texture tools, or the legacy DirectX SDK ``DXTex.exe`` tool. Therefore, the default behavior is to prefer to use 'legacy' pixel formats when possible.
The 'DX10' header is not supported by D3DX9, older Direct3D 9 era texture tools, or the legacy DirectX SDK ``DXTex.exe`` tool. Therefore, the default behavior is to prefer to use 'legacy' DirectDraw pixel formats when possible.
Note that for Direct3D 11.1 video formats, only ``DXGI_FORMAT_YUY2`` is supported by Direct3D 9. Legacy ``DDS`` files containing FourCC "UYVY" are converted to YUY2 at load-time.
# Windows Store apps
[File access and permissions (Windows Runtime apps)](https://msdn.microsoft.com/en-us/library/windows/apps/hh967755.aspx)
[File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions)
## Load
If you wish to load a texture from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use LoadFromDDSFile on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
```cpp
// Using C++/CX (/ZW) and the Parallel Patterns Library (PPL)
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
if (file)
{
if (file)
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
{
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
if ( tempFile )
{
if ( tempFile )
{
HRESULT hr = LoadFromDDSFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
HRESULT hr = LoadFromDDSFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
});
}
```
## Save
For SaveToDDSFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:
For ``SaveToDDSFile`` to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```
If you are going to immediately copy it to another location via StorageFolder, then use the app's temporary folder:
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```
# Further reading
[The DDS File Format Lives](http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx)
[DDS Programmer's Guide](http://msdn.microsoft.com/en-us/library/bb943991.aspx)
[DDS Programmer's Guide](https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dx-graphics-dds-pguide)

34
Decompress.md

@ -1,11 +1,13 @@
Decompresses a block-compressed (BC) image or set of BC images.
Decompresses a block-compressed (BC) image or set of BC images.
HRESULT Decompress( const Image& cImage, DXGI_FORMAT format,
ScratchImage& image );
```cpp
HRESULT Decompress( const Image& cImage, DXGI_FORMAT format,
ScratchImage& image );
HRESULT Decompress( const Image* cImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, ScratchImage& images );
HRESULT Decompress( const Image* cImages, size_t nimages,
const TexMetadata& metadata,
DXGI_FORMAT format, ScratchImage& images );
```
# Parameters
@ -15,19 +17,21 @@ _format_: Format to decompress to. If set to ``DXGI_FORMAT_UNKNOWN`` the routine
# Example
ScratchImage bcImage;
```cpp
ScratchImage bcImage;
...
ScratchImage destImage;
hr = Decompress( bcImage.GetImages(), bcImage.GetImageCount(),
bcImage.GetMetadata(),
DXGI_FORMAT_UNKNOWN, destImage );
if ( FAILED(hr) )
...
ScratchImage destImage;
hr = Decompress( bcImage.GetImages(), bcImage.GetImageCount(),
bcImage.GetMetadata(),
DXGI_FORMAT_UNKNOWN, destImage );
if ( FAILED(hr) )
...
```
# Remark
The DirectXTex library functions allow arbitrary sized images to handle non-power-of-2 mipmapped BC textures. Note that Direct3D will not allow a resource to be created using BC format with the top-level size set to something other than a multiple of 4 in width and height, even though it does allow the mipchain below it to _not_ meet that requirement. In other words, the library allows some textures to be decompressed that are not actually valid on Direct3D 11.
The DirectXTex library functions allow arbitrary sized images to handle non-power-of-2 mipmapped BC textures. Note that Direct3D will not allow a resource to be created using BC format with the top-level size set to something other than a multiple of 4 in width and height, even though it does allow the mipchain below it to _not_ meet that requirement. In other words, the library allows some textures to be decompressed that are not actually valid on Direct3D.
See [[Compress]]

60
DirectXTex.md

@ -1,31 +1,41 @@
The DirectXTex library includes a full-featured ``DDS`` reader and writer including legacy format conversions, a ``TGA`` reader and writer, a ``HDR`` reader and writer, a WIC-based bitmap reader and writer (``BMP``, ``JPEG``, ``PNG``, ``TIFF``, and HD Photo), and various texture processing functions. This is intended primarily for tool usage--for runtime use, see [DirectX Tool Kit](https://github.com/Microsoft/DirectXTK).
The DirectXTex library includes a full-featured ``DDS`` reader and writer including legacy format conversions, a ``TGA`` reader and writer, a ``HDR`` reader and writer, a WIC-based bitmap reader and writer (``BMP``, ``JPEG``, ``PNG``, ``TIFF``, and HD Photo), and various texture processing functions.
This library is intended primarily for tool usage. For a library that is more optimized for runtime use, see _DirectX Tool Kit_ for [DX11](https://github.com/Microsoft/DirectXTK) / [DX12](https://github.com/Microsoft/DirectXTK12).
> Support for ``EXR`` requires the OpenEXR library and additional code. See [[Adding OpenEXR]] for more details.
# Headers
The majority of the header files here are intended for internal implementation of the library only (BC.h, DDS.h, DirectXTexP.h, and scoped.h). Only **DirectXTex.h** (and **DirectXTex.inl**) is meant as a 'public' header for the library.
```cpp
#include "DirectXTex.h"
```
> By default, the library supports Direct3D 11. If you want to support Direct3D 12, then you need to ``#include <d3d12.h>`` before you do ``#include "DirectXMesh.h"``.
# Namespace
All the functions in the library are in the **DirectX** C++ namespace.
# Initialization
The library assumes that the client code will have already called ``CoInitialize``, ``CoInitializeEx``, or ``Windows::Foundation::Initialize`` as needed by the application before calling any DirectXTex routines. Most DirectXTex functions use the [Windows Imaging Component](https://msdn.microsoft.com/en-us/library/windows/desktop/ee719654.aspx) which requires COM.
The library assumes that the client code will have already called ``CoInitialize``, ``CoInitializeEx``, or ``Windows::Foundation::Initialize`` as needed by the application before calling any DirectXTex routines. Most DirectXTex functions use the [Windows Imaging Component](https://docs.microsoft.com/en-us/windows/desktop/wic/-wic-about-windows-imaging-codec) which requires COM.
For a Universal Windows Platform (UWP) app, the Windows Runtime and COM is initialized by the C/C++ Run-Time. For a classic Windows desktop application you have to do this explicitly:
#if (_WIN32_WINNT >= 0x0A00 /*_WIN32_WINNT_WIN10*/)
Microsoft::WRL::Wrappers::RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
// error
#else
HRESULT hr = CoInitializeEx(nullptr, COINITBASE_MULTITHREADED);
if (FAILED(hr))
// error
#endif
```cpp
#if (_WIN32_WINNT >= 0x0A00 /*_WIN32_WINNT_WIN10*/)
Microsoft::WRL::Wrappers::RoInitializeWrapper initialize(RO_INIT_MULTITHREADED);
if (FAILED(initialize))
// error
#else
HRESULT hr = CoInitializeEx(nullptr, COINITBASE_MULTITHREADED);
if (FAILED(hr))
// error
#endif
```
# Functions
## DDS I/O Functions
These functions perform file I/O for [DirectDraw Surface](https://msdn.microsoft.com/en-us/library/bb943991.aspx) (``.DDS``) files. These functions support many legacy Direct3D 9 ``.DDS`` files and all [Direct3D 10.x/11.x era](http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx) ``DX10`` extension ``.DDS`` files.
These functions perform file I/O for [DirectDraw Surface](https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dx-graphics-dds-pguide) (``.DDS``) files. These functions support many legacy Direct3D 9 ``.DDS`` files and all [Direct3D 10.x/11.x era](http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx) ``DX10`` extension ``.DDS`` files.
* **GetMetadataFromDDSMemory** - Extracts the metadata from a ``DDS`` file in memory
* **GetMetadataFromDDSFile** - Extracts the metadata from a ``DDS`` file on disk
@ -61,7 +71,7 @@ The [Targa Truevision](http://en.wikipedia.org/wiki/Truevision_TGA) (``.TGA``) f
See [[TGA I/O Functions]]
## WIC I/O Functions
These functions use the [Windows Imaging Component](https://msdn.microsoft.com/en-us/library/windows/desktop/ee719654.aspx) (WIC) to read or write an image file. There are built-in WIC codecs in Windows for ``.BMP``, ``.PNG``, ``.GIF``, ``.TIFF``, ``.JPEG``, and JPEG-XR / HD Photo images. Some containers (``.GIF`` and ``.TIFF``) can contain multi-frame bitmaps files.
These functions use the [Windows Imaging Component](https://docs.microsoft.com/en-us/windows/desktop/wic/-wic-about-windows-imaging-codec) (WIC) to read or write an image file. There are built-in WIC codecs in Windows for ``.BMP``, ``.PNG``, ``.GIF``, ``.TIFF``, ``.JPEG``, and JPEG-XR / HD Photo images. Some containers (``.GIF`` and ``.TIFF``) can contain multi-frame bitmaps files.
* **GetMetadataFromWICMemory** - Extracts the metadata from a WIC-supported file in memory
* **GetMetadataFromWICFile** - Extracts the metadata from a WIC-supported file on disk
@ -143,9 +153,10 @@ _Note if there is no format that matches the desired property for the input form
# Structures
**TexMetadata** contains metadata information about the texture resource and organization such as width, height, depth, format, dimension, etc.
* ``TEX_DIMENSION_TEXTURE1D``, ``TEX_DIMENSION_TEXTURE2D``, and ``TEX_DIMENSION_TEXTURE3D`` are aliases for ``D3D10_RESOURCE_DIMEMSION`` and ``D3D11_RESOURCE_DIMENSION``.
* ``TEX_MISC_TEXTURECUBE`` is an alias for the same ``D3D10_RESOURCE_MISC_FLAG`` and ``D3D11_RESOURCE_MISC_FLAG``.
* ``TEX_MISC2_ALPHA_MODE_MASK`` is a mask for miscFlags2 to obtain the ``TEX_ALPHA_MODE``.
* ``TEX_DIMENSION_TEXTURE1D``, ``TEX_DIMENSION_TEXTURE2D``, and ``TEX_DIMENSION_TEXTURE3D`` are aliases for ``D3D10_RESOURCE_DIMEMSION`` and ``D3D11_RESOURCE_DIMENSION``.
* ``TEX_MISC_TEXTURECUBE`` is an alias for the same ``D3D10_RESOURCE_MISC_FLAG`` and ``D3D11_RESOURCE_MISC_FLAG``.
* ``TEX_MISC2_ALPHA_MODE_MASK`` is a mask for _miscFlags2_ to obtain the ``TEX_ALPHA_MODE``.
**Image** contains information about the surface including width, height, format, rowPitch, slicePitch, and a pointer to pixel data. Note that for 1D and 2D images, slicePitch should be set to the full size of the image.
@ -162,15 +173,15 @@ In your application's solution, right-click on the Solution and use "Add \ Exist
<table>
<tr>
<td>DirectXTex_Desktop_2017</td>
<td>Windows desktop applications for Windows Vista SP2 or later building with VS 2017 Community, Professional or higher with the Windows 10 SDK (17134).</td>
<td>Windows desktop applications for Windows Vista SP2 or later building with VS 2017 Community, Professional or higher with the Windows 10 SDK (17763).</td>
</tr>
<tr>
<td>DirectXTex_Desktop_2017_Win10</td>
<td>Windows desktop applications for Windows 10 building with VS 2017 Community, Professional or higher with the Windows 10 SDK (17134).<br /><I>This includes DirectX 12 support.</I></td>
<td>Windows desktop applications for Windows 10 building with VS 2017 Community, Professional or higher with the Windows 10 SDK (17763).<br /><I>This includes DirectX 12 support.</I></td>
</tr>
<tr>
<td>DirectXTex_Windows10</td>
<td>Universal Windows Platform (UWP) apps building with VS 2017 with the Windows 10 SDK (17134).<br /><I>This includes DirectX 12 support.</I></td>
<td>Universal Windows Platform (UWP) apps building with VS 2017 with the Windows 10 SDK (17763).<br /><I>This includes DirectX 12 support.</I></td>
</tr>
<tr>
<td>DirectXTex_XboxOneXDK_2017</td>
@ -178,7 +189,7 @@ In your application's solution, right-click on the Solution and use "Add \ Exist
</tr>
</table>
> For VS 2017, use of the [15.7 update](https://blogs.msdn.microsoft.com/chuckw/2018/05/07/vs-2017-15-7-update/) or later is recommended.
> For VS 2017, use of the [15.8 update](https://blogs.msdn.microsoft.com/chuckw/2018/08/16/vs-2017-15-8-update/) or [15.9 update](https://blogs.msdn.microsoft.com/chuckw/2018/11/15/vs-2017-15-9-update/) is recommended.
<table>
<tr>
@ -201,27 +212,28 @@ In your application's solution, right-click on the Solution and use "Add \ Exist
> For VS 2015, use of the [Update 3](https://blogs.msdn.microsoft.com/chuckw/2016/06/27/visual-studio-2015-update-3/) is recommended.
In your application's project, right-click on the **Project** and use "References...", then "Add New Reference...", and then check the DirectXTex project name and click OK. For a universal Windows app, Windows Store app, Windows phone, or Xbox One solution, you need to set _Reference Assembly Output_ to false since DirectXTex is a static C++ library and not a WinRT component.
In your application's project, right-click on the **Project** and use "References...", then "Add New Reference...", and then check the DirectXTex project name and click OK. For a Universal Windows Platform (UWP) app, Windows Store app, Windows phone, or Xbox One solution, you need to set _Reference Assembly Output_ to false since DirectXTex is a static C++ library and not a WinRT component.
In your application's project settings, on the "C++ / General" page set Configuration to "All Configurations", set Platform to "All Platforms", and then add the relative path to `DirectXTex;`--assuming you have the DirectXTex folder in the same directory as your ``sln`` file, it should be `$(SolutionDir$)\DirectXTex;`--to the _Additional Include Directories_ properties. Click Apply.
See the [Visual C++ Team Blog](http://blogs.msdn.com/b/vcblog/archive/2010/05/03/flexible-project-to-project-references.aspx)
**Note:** DirectXTex is not supported on Windows Phone 8.0, because WIC is not available on that platform. The ``.DDS`` files it generates are suitable for use on Windows Phone 8.x assuming the pixel format is supported by the device (currently Feature Level 9.3).
> DirectXTex was never supported on Windows Phone 8.0, because WIC is not available on that platform. The ``.DDS`` files it generates are suitable for use on Windows Phone 8.x assuming the pixel format is supported by the device (Feature Level 9.3).
## Using NuGet package manager
Alternatively you can use NuGet to install one of the DirectXTex packages. Use *Project / Manage NuGet Packages...* then select "Online" and search for "DirectXTex".
* Use Id: [directxtex_desktop_2015](https://www.nuget.org/packages/directxtex_desktop_2015/) for Windows desktop C++ applications building with VS 2015 or VS 2017 Community, VS 2015 or VS 2017 Professional or higher.
* Use Id: [directxtex_desktop_2015_win10](https://www.nuget.org/packages/directxtex_desktop_win10/) for Windows desktop C++ applications building with VS 2015 or VS 2017 Community, VS 2015 or VS 2017 Professional or higher for Windows 10. _This includes DirectX 12 support._
* Use id: [directxtex_uwp](https://www.nuget.org/packages/directxtex_uwp/) for Universal Windows Platform apps for Windows 10 building with VS 2015 or VS 2017 Community, VS 2015 or VS 2017 Professional or higher. _This includes DirectX 12 support._
You should use the NuGet interface to check for updates if you have an older version installed.
# Release Notes
* The alpha mode specification for ``DDS`` files was updated between the March 2013 and April 2013 releases. Any DDS files created using the ``DDS_FLAGS_FORCE_DX10_EXT_MISC2`` flag or the [[texconv]] ``-dx10`` switch using the March 2013 release should be refreshed.
* The alpha mode specification for ``DDS`` files was updated between the March 2013 and April 2013 releases. Any ``DDS`` files created using the ``DDS_FLAGS_FORCE_DX10_EXT_MISC2`` flag or the [[texconv]] ``-dx10`` switch using the March 2013 release should be refreshed.
* Due to the underlying Windows BMP WIC codec, alpha channels are not supported for 16bpp or 32bpp BMP pixel format files. The Windows 8.x and Windows 10 version of the Windows BMP WIC codec does support 32bpp pixel formats with alpha when using the ``BITMAPV5HEADER`` file header. Note the updated WIC is available on Windows 7 SP1 with [KB 2670838](http://support.microsoft.com/kb/2670838) installed.
* While DXGI 1.0 and DXGI 1.1 include 5:6:5 (``DXGI_FORMAT_B5G6R5_UNORM``) and 5:5:5:1 (``DXGI_FORMAT_B5G5R5A1_UNORM``) pixel format enumerations, the DirectX 10.x and 11.0 Runtimes do not support these formats for use with Direct3D. The DirectX 11.1 runtime, DXGI 1.2, and the WDDM 1.2 driver model fully support 16bpp formats (5:6:5, 5:5:5:1, and 4:4:4:4).
* While DXGI 1.0 and DXGI 1.1 include 5:6:5 (``DXGI_FORMAT_B5G6R5_UNORM``) and 5:5:5:1 (``DXGI_FORMAT_B5G5R5A1_UNORM``) pixel format enumerations, the DirectX 10.x and 11.0 Runtimes do not support these formats for use with Direct3D. The DirectX 11.1 runtime, DXGI 1.2, and the WDDM 1.2 driver model or later fully support 16bpp formats (5:6:5, 5:5:5:1, and 4:4:4:4).
* Loading of 96bpp floating-point TIFF files results in a corrupted image prior to Windows 8. This fix is available on Windows 7 SP1 with [KB 2670838](http://support.microsoft.com/kb/2670838) installed.

50
EvaluateImage.md

@ -1,16 +1,18 @@
Evaluates a user-supplied function across an image.
HRESULT EvaluateImage(const Image& image,
std::function<
void(const XMVECTOR* pixels, size_t width, size_t y)
> pixelFunc );
```cpp
HRESULT EvaluateImage(const Image& image,
std::function<
void(const XMVECTOR* pixels, size_t width, size_t y)
> pixelFunc );
HRESULT EvaluateImage(const Image* images, size_t nimages, const TexMetadata& metadata,
std::function<
void(const XMVECTOR* pixels, size_t width, size_t y)
> pixelFunc );
HRESULT EvaluateImage(const Image* images, size_t nimages, const TexMetadata& metadata,
std::function<
void(const XMVECTOR* pixels, size_t width, size_t y)
> pixelFunc );
```
**Breaking change notice:** The first release of this function was ``Evaluate`` but this generic name can cause conflicts in some client code so it was renamed ``EvaluateImage``.
> **Breaking change notice:** In the September 2016 release this function was ``Evaluate`` but this generic name can cause conflicts in some client code so it was renamed ``EvaluateImage``.
# Parameters
@ -20,24 +22,26 @@ _pixelFunc_: A callback function to invoke for each scanline of the image.
This function computes the maximum luminance of an input.
XMVECTOR maxLum = XMVectorZero();
HRESULT hr = EvaluateImage(*image.GetImage(0, 0, 0),
[&](const XMVECTOR* pixels, size_t width, size_t y)
```cpp
XMVECTOR maxLum = XMVectorZero();
HRESULT hr = EvaluateImage(*image.GetImage(0, 0, 0),
[&](const XMVECTOR* pixels, size_t width, size_t y)
{
UNREFERENCED_PARAMETER(y);
for (size_t j = 0; j < width; ++j)
{
UNREFERENCED_PARAMETER(y);
for (size_t j = 0; j < width; ++j)
{
static const XMVECTORF32 s_luminance = { 0.3f, 0.59f, 0.11f, 0.f };
static const XMVECTORF32 s_luminance = { 0.3f, 0.59f, 0.11f, 0.f };
XMVECTOR v = *pixels++;
XMVECTOR v = *pixels++;
v = XMVector3Dot(v, s_luminance);
v = XMVector3Dot(v, s_luminance);
maxLum = XMVectorMax(v, maxLum);
}
});
if (FAILED(hr))
...
maxLum = XMVectorMax(v, maxLum);
}
});
if (FAILED(hr))
...
```
# Remarks
Image data is converted to ``DXGI_FORMAT_R32G32B32A32_FLOAT`` for this operation. BC data is automatically decompressed.

11
Filter-Flags.md

@ -1,4 +1,6 @@
enum TEX_FILTER_FLAGS
```cpp
enum TEX_FILTER_FLAGS
```
``TEX_FILTER_DEFAULT`` Default flags
@ -7,9 +9,9 @@ This selects the filtering mode used for resizing and mipmap generation. In most
* ``TEX_FILTER_POINT`` Nearest neighbhor
* ``TEX_FILTER_LINEAR`` Bilinear/Trilinear interpolation
* ``TEX_FILTER_CUBIC`` Bicubic/Tricubic interpoloation
* ``TEX_FILTER_FANT`` Fant which is euivalent to a box filter for down-scaling.
* ``TEX_FILTER_FANT`` Fant which is equivalent to a box filter for down-scaling.
* ``TEX_FILTER_BOX`` Box filter (alias for Fant since they are equivalent for down-scaling). When using the non-WIC codepaths, Box filter fails if the texture is not a power of 2 in width & height.
* ``TEX_FILTER_TRIANGLE`` Finite low-pass triangle filter.
* ``TEX_FILTER_TRIANGLE`` Finite low-pass triangle filter. _This is not supported by WIC so always uses custom filtering paths._
> The legacy D3DX library implemented Point, Linear, Box, and Triangle.
@ -34,7 +36,7 @@ This controls how edge pixels are filtered. It defaults to CLAMP which is the on
This controls color space transformation for conversions.
* ``TEX_FILTER_SRGB_IN`` Indicates the input format is the sRGB format. This is implied if using a ``DXGI_FORMAT_*_SRGB`` format
* ``TEX_FILTER_SRGB_OUT`` Indicates the output format is the sRGB format. This is implied if using a ``DXGI_FORMAT_*_SRGB`` format
* ``TEX_FILTER_SRGB`` This is the same as setting both ``TEX_FILTER_SRGB_IN`` and ``TEX_FILTER_SRGB_OUT``
* ``TEX_FILTER_SRGB`` This is the same as setting both ``TEX_FILTER_SRGB_IN`` and ``TEX_FILTER_SRGB_OUT``
_The [sRGB color space](http://en.wikipedia.org/wiki/SRGB) overall is approximately equivalent to gamma 2.2. It's actually linear below a threshold, and gamma 2.4 beyond that._
@ -55,4 +57,3 @@ For Convert operations, these flags control special-case logic in the non-WIC pa
For Convert operations, these flags enable special-case logic in the non-WIC paths.
* ``TEX_FILTER_FLOAT_X2BIAS`` Enables special ``*2 -1`` conversion cases for converting unorm <-> float, and positive-only-floats <-> float/snorm. These are typically used with normal maps.

29
FlipRotate.md

@ -1,10 +1,12 @@
Flip and/or rotate an image.
HRESULT FlipRotate( const Image& srcImage, DWORD flags, ScratchImage& image );
```cpp
HRESULT FlipRotate( const Image& srcImage, DWORD flags, ScratchImage& image );
HRESULT FlipRotate( const Image* srcImages, size_t nimages,
const TexMetadata& metadata
DWORD flags, ScratchImage& result );
HRESULT FlipRotate( const Image* srcImages, size_t nimages,
const TexMetadata& metadata
DWORD flags, ScratchImage& result );
```
# Parameters
@ -22,20 +24,21 @@ Optionally a flip
# Example
ScratchImage srcImage;
```cpp
ScratchImage srcImage;
...
ScratchImage destImage;
hr = FlipRotate( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(),
TEX_FR_FLIP_HORIZONTAL, destImage );
if ( FAILED(hr) )
...
ScratchImage destImage;
hr = FlipRotate( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(),
TEX_FR_FLIP_HORIZONTAL, destImage );
if ( FAILED(hr) )
...
```
# Remarks
This function does not operate directly on block compressed images. See [[Decompress]] and [[Compress]].
This function cannot operate directly on a planar format image. See [[ConvertToSinglePlane]] for a method for converting planar data to a format that is supported by this routine.

38
GenerateMipMaps.md

@ -1,19 +1,21 @@
Generates mipmaps for an image or a set of images.
**Note:** This generates mipmaps for 1D and 2D dimension textures. For 3D dimension textures, see [[GenerateMipMaps3D]].
> This generates mipmaps for 1D and 2D dimension textures. For 3D dimension textures (a.k.a. volume maps), see [[GenerateMipMaps3D]].
HRESULT GenerateMipMaps( const Image& baseImage, DWORD filter,
size_t levels,
ScratchImage& mipChain, bool allow1D = false );
```cpp
HRESULT GenerateMipMaps( const Image& baseImage, DWORD filter,
size_t levels,
ScratchImage& mipChain, bool allow1D = false );
HRESULT GenerateMipMaps( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DWORD filter, size_t levels,
ScratchImage& mipChain );
```
HRESULT GenerateMipMaps( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DWORD filter, size_t levels,
ScratchImage& mipChain );
# Parameters
_baseImage_: The mipmap chain is created by repeatedly down-sizing a base image. The first level of the resulting mipChain is set to a copy of the input baseImage.
_baseImage_: The mipmap chain is created by repeatedly down-sizing a base image. The first level of the resulting _mipChain_ is set to a copy of the input baseImage.
_filter_: See [[Filter Flags]]
@ -23,15 +25,18 @@ _allow1D_: If set to true and given an input baseImage with a height of 1 then t
# Example
ScratchImage baseImage;
```cpp
ScratchImage baseImage;
...
ScratchImage mipChain;
hr = GenerateMipMaps( baseImage.GetImages(), baseImage.GetImageCount(),
baseImage.GetMetadata(), TEX_FILTER_DEFAULT, 0, mipChain );
if ( FAILED(hr) )
...
```
ScratchImage mipChain;
hr = GenerateMipMaps( baseImage.GetImages(), baseImage.GetImageCount(),
baseImage.GetMetadata(), TEX_FILTER_DEFAULT, 0, mipChain );
if ( FAILED(hr) )
...
# Remarks
This function does not operate directly on block compressed images. See [[Decompress]] and [[Compress]].
@ -46,4 +51,3 @@ This function is implemented with both WIC and non-WIC code paths. The WIC code
* When resizing HDR images, be sure to stick with the default of ``TEX_FILTER_FANT`` when using WIC as the ``IWICBitmapScalar`` has limited supported for high bit-depth and extended range formats. By default, the DirectXTex library chooses to use non-WIC codepaths when generating mipmaps for > 8 color-depth images with LINEAR or CUBIC filtering, with sRGB images, with MIRROR/WRAP semantics, or when using TRIANGLE filtering. It will also select non-WIC paths when dealing with 16k textures that are too large for WIC.
* On Windows 10 Creators Update (16299) or later, WIC has better handling when using the ``IWICBitmapScalar`` with 10:10:10:2 and float16 formats. On older versions of Windows, it will return the results for these formats as 32bpp which is then reconverted to the target format but with a loss of precision. You may want to use ``TEX_FILTER_FORCE_NON_WIC`` if the results you are getting appear to be losing precision on older releases of Windows.

38
GenerateMipMaps3D.md

@ -1,19 +1,21 @@
Generates mipmaps for a 3D volume texture from a set of images representing the slices.
**Note:** This generates mipmaps for 3D dimension textures. For 1D and 2D dimension textures, see [[GenerateMipMaps]].
> This generates mipmaps for 3D dimension textures (a.k.a. volume textures). For 1D and 2D dimension textures, see [[GenerateMipMaps]].
HRESULT GenerateMipMaps3D( const Image* baseImages, size_t depth,
DWORD filter, size_t levels,
ScratchImage& mipChain );
```cpp
HRESULT GenerateMipMaps3D( const Image* baseImages, size_t depth,
DWORD filter, size_t levels,
ScratchImage& mipChain );
HRESULT GenerateMipMaps3D( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DWORD filter, size_t levels,
ScratchImage& mipChain );
HRESULT GenerateMipMaps3D( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
DWORD filter, size_t levels,
ScratchImage& mipChain );
```
# Parameters
_baseImages_/_srcImages_: The mipmap chain is created by repeatedly down-sizing the slices of base images. The first level of the resulting mipChain is set to a copy of the input baseImages.
_baseImages_/_srcImages_: The mipmap chain is created by repeatedly down-sizing the slices of base images. The first level of the resulting _mipChain_ is set to a copy of the input baseImages.
_depth_: The Z dimension of the volume texture which is also the number of slices in the baseImages array.
@ -23,15 +25,17 @@ _levels_: Number of mip map levels including base. A value of 0 indicates creati
# Example
ScratchImage baseImages;
```cpp
ScratchImage baseImages;
...
ScratchImage mipChain;
hr = GenerateMipMaps3D( baseImages.GetImages(), baseImages.GetImageCount(),
baseImages.GetMetadata(), TEX_FILTER_DEAFULT, 0, mipChain );
if ( FAILED(hr) )
...
ScratchImage mipChain;
hr = GenerateMipMaps3D( baseImages.GetImages(), baseImages.GetImageCount(),
baseImages.GetMetadata(), TEX_FILTER_DEAFULT, 0, mipChain );
if ( FAILED(hr) )
...
```
# Remarks
@ -43,4 +47,4 @@ Each miplevel of a 3D volume texture is half the size in width & height and half
This function does not make use of WIC for resizing since volume textures require 3D filtering methods.
**Note:** All slices in a miplevel must be in contiguous memory for working with Direct3D 11, which is how _ScratchImage_ is implemented.
**Note:** All slices in a miplevel must be in contiguous memory for working with Direct3D, which is how _ScratchImage_ is implemented.

8
GetWICCodec.md

@ -1,6 +1,8 @@
Returns a WIC GUID for a given file container given a simple enumeration value. This function is optional and you can instead use the WIC container GUID directly instead.
REFGUID GetWICCodec( _In_ WICCodecs codec );
```cpp
REFGUID GetWICCodec( _In_ WICCodecs codec );
```
# Parameters
@ -15,7 +17,7 @@ The _codecs_ enumeration is one of the following values:
* ``WIC_CODEC_ICO`` Windows Icon (``.ico``)
# Remarks
The primary benefit of this function is that you don't require including ``<wincodec.h>`` for every client module that calls DirectXTex's [[WIC I/O Functions]].
The primary benefit of this function is that you do not have to include ``<wincodec.h>`` for every client module that calls DirectXTex's [[WIC I/O Functions]].
# Platform notes
Do not use ``WIC_CODEC_WMP`` for Xbox One XDK applications as the WMP / HD Photo WIC codec is not supported by that platform.
Do not use ``WIC_CODEC_WMP`` for Xbox One XDK applications as the WMP / HD Photo WIC codec is not supported by that platform.

114
HDR-I-O-Functions.md

@ -1,22 +1,26 @@
The [Radiance RGBE](https://en.wikipedia.org/wiki/RGBE_image_format) (``.HDR``) format is commonly used as a texture source file format in game development for high-dynamic range images, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.
# GetMetadataFromHDRMemory, GetMetadataFromHDRFile
Returns the _TexMetadata_ from a ``.HDR`` file.
Returns the _TexMetadata_ metadata from a ``.HDR`` file.
HRESULT GetMetadataFromHDRMemory( const void* pSource, size_t size,
TexMetadata& metadata );
```cpp
HRESULT GetMetadataFromHDRMemory( const void* pSource, size_t size,
TexMetadata& metadata );
HRESULT GetMetadataFromHDRFile( const wchar_t* szFile,
TexMetadata& metadata );
HRESULT GetMetadataFromHDRFile( const wchar_t* szFile,
TexMetadata& metadata );
```
# LoadFromHDRMemory, LoadFromHDRFile
Loads a ``.HDR`` file.
HRESULT LoadFromHDRMemory( const void* pSource, size_t size,
TexMetadata* metadata, ScratchImage& image );
```cpp
HRESULT LoadFromHDRMemory( const void* pSource, size_t size,
TexMetadata* metadata, ScratchImage& image );
HRESULT LoadFromHDRFile( const wchar_t* szFile,
TexMetadata* metadata, ScratchImage& image );
HRESULT LoadFromHDRFile( const wchar_t* szFile,
TexMetadata* metadata, ScratchImage& image );
```
* The data is always loaded as ``R32G32B32A32_FLOAT`` with the alpha channel always set to 1.
* If the file contains a ``32-bit_rle_xyze`` header, no color space conversions are performed and the data is read "as is".
@ -24,9 +28,11 @@ Loads a ``.HDR`` file.
# SaveToHDRMemory, SaveToHDRFile
Saves an image to a ``.HDR`` file.
HRESULT SaveToHDRMemory( const Image& image, Blob& blob );
```cpp
HRESULT SaveToHDRMemory( const Image& image, Blob& blob );
HRESULT SaveToHDRFile( const Image& image, const wchar_t* szFile );
HRESULT SaveToHDRFile( const Image& image, const wchar_t* szFile );
```
* ``R32G32B32A32_FLOAT`` and ``R32G32B32_FLOAT`` data are supported for writing. Alpha channel information is ignore when writing the ``.HDR`` file.
* Always writes using the ``32-bit_rle_rgbe`` format
@ -37,31 +43,37 @@ For the load functions, the _metadata_ parameter can be nullptr as this informat
# Examples
This is a simple loading example. The ``HDR`` format cannot contain complicated multi-image formats, so the _TexMetadata_ info is redundant information.
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromHDRFile( L"uffizi_cross.hdr", nullptr, *image );
if ( FAILED(hr) )
// error
```cpp
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromHDRFile( L"uffizi_cross.hdr", nullptr, *image );
if ( FAILED(hr) )
// error
```
A ``HDR`` file can only store one 2D image.
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToHDRFile( *img, L"NEW_IMAGE.HDR" );
if ( FAILED(hr) )
// error
```cpp
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToHDRFile( *img, L"NEW_IMAGE.HDR" );
if ( FAILED(hr) )
// error
```
You can also save data directly from memory without using the intermediate **ScratchImage** at all. This example assumes a single 2D image is being written out.
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /* DXGI_FORMAT_R32G32B32A32_FLOAT or DXGI_FORMAT_R32G32B32_FLOAT */;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToHDRFile( img, L"NEW_IMAGE.HDR" );
if ( FAILED(hr) )
// error
```cpp
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /* DXGI_FORMAT_R32G32B32A32_FLOAT or DXGI_FORMAT_R32G32B32_FLOAT */;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToHDRFile( img, L"NEW_IMAGE.HDR" );
if ( FAILED(hr) )
// error
```
# Implementation Notes
@ -69,43 +81,47 @@ You can also save data directly from memory without using the intermediate **Scr
# Windows Store apps
[File access and permissions (Windows Runtime apps)](https://msdn.microsoft.com/en-us/library/windows/apps/hh967755.aspx)
[File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions)
## Load
If you wish to load an image from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use LoadFromHDRFile on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
```cpp
// Using C++/CX (/ZW) and the Parallel Patterns Library (PPL)
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
if (file)
{
if (file)
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
{
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
if ( tempFile )
{
if ( tempFile )
{
HRESULT hr = LoadFromHDRFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
HRESULT hr = LoadFromHDRFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
});
}
```
## Save
For SaveToHDRFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```
If you are going to immediately copy it to another location via StorageFolder, then use the app's temporary folder:
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```
# Further reading
Greg Ward, "Real Pixels", *Graphics Gems II*, James Arvo (editor), Academic Press, 1991, ISBN: 0120644819, p. 80-83 ([code](http://www.realtimerendering.com/resources/GraphicsGems/gemsii/RealPixels/))
[High Dynamic Range Image Encodings](http://www.anyhere.com/gward/hdrenc/hdr_encodings.html)

7
Home.md

@ -1,6 +1,6 @@
http://go.microsoft.com/fwlink/?LinkId=248926
![DirectX Logo](https://github.com/Microsoft/DirectXTex/wiki/X_jpg.jpg) **DirectXTex**, a shared source library for reading and writing ``.DDS`` files, and performing various texture content processing operations including resizing, format conversion, mip-map generation, block compression for Direct3D runtime texture resources, and height-map to normal-map conversion. This library makes use of the Windows Image Component (WIC) APIs. It also includes simple ``.TGA`` and ``.HDR`` readers and writers since these image file format are commonly used for texture content processing pipelines, but are not currently supported by a built-in WIC codec.
![DirectX Logo](https://github.com/Microsoft/DirectXTex/wiki/X_jpg.jpg) **DirectXTex**, a shared source library for reading and writing ``.DDS`` files, and performing various texture content processing operations including resizing, format conversion, mip-map generation, block compression for Direct3D runtime texture resources, and height-map to normal-map conversion. This library makes use of the Windows Image Component (WIC) APIs. It also includes simple ``.TGA`` and ``.HDR`` readers and writers since these image file format are commonly used for texture content processing pipelines, but are not supported by a built-in WIC codec.
See this [blog post](http://blogs.msdn.com/b/chuckw/archive/2011/10/28/directxtex.aspx) for an overview.
@ -27,7 +27,7 @@ See [this post](http://blogs.msdn.com/b/chuckw/archive/2013/08/21/living-without
# DirectXTex vs. DirectX Tool Kit
The _DirectXTex_ library is designed a full-featured texture processing library that includes a sophisticated DDS file reader. This reader can handle numerous legacy formats and automatically performs required conversions. This makes it extremely useful in tools and content pipelines, but is far more code that is really needed for a game or application at runtime that loads 'cooked' textures.
Instead, a game or application should make use of **DDSTextureLoader** ([DX11](https://github.com/Microsoft/DirectXTK/wiki/DDSTextureLoader) or [DX12](https://github.com/Microsoft/DirectXTK12/wiki/DDSTextureLoader)) and/or **WICTextureLoader** ([DX11](https://github.com/Microsoft/DirectXTK/wiki/WICTextureLoader) or [DX12](https://github.com/Microsoft/DirectXTK12/wiki/WICTextureLoader)). These modules provide light-weight versions of texture creation from ``.dds``, ``.bmp``, ``.png``, ``.gif``, ``.jpg``, ``.tif``, and JPEG-XR / HD Photo files. **ScreenGrab** ([DX11](https://github.com/Microsoft/DirectXTK/wiki/ScreenGrab) or [DX12](https://github.com/Microsoft/DirectXTK12/wiki/ScreenGrab))is a light-weight screenshot capture utility for writing out the same file types.
Instead, a game or application should make use of **DDSTextureLoader** ([DX11](https://github.com/Microsoft/DirectXTK/wiki/DDSTextureLoader) or [DX12](https://github.com/Microsoft/DirectXTK12/wiki/DDSTextureLoader)) and/or **WICTextureLoader** ([DX11](https://github.com/Microsoft/DirectXTK/wiki/WICTextureLoader) or [DX12](https://github.com/Microsoft/DirectXTK12/wiki/WICTextureLoader)). These modules provide light-weight versions of texture creation from ``.dds``, ``.bmp``, ``.png``, ``.gif``, ``.jpg``, ``.tif``, and JPEG-XR / HD Photo files. **ScreenGrab** ([DX11](https://github.com/Microsoft/DirectXTK/wiki/ScreenGrab) or [DX12](https://github.com/Microsoft/DirectXTK12/wiki/ScreenGrab)) is a light-weight screenshot capture utility for writing out the same file types.
These modules are included in _DirectX Tool Kit_ ([DX11](http://go.microsoft.com/fwlink/?LinkId=248929) and [DX12](http://go.microsoft.com/fwlink/?LinkID=615561)), and there are 'standalone' versions available in the _DirectXTex_ distribution as well.
@ -43,6 +43,7 @@ There is another version of the _DirectXTex_ library and the ``texconv`` utility
The various video independent hardware vendors (IHVs) have their own texture toolsets as well.
* [AMD Compress](http://developer.amd.com/tools-and-sdks/graphics-development/amdcompress/) and [Compressonator](http://gpuopen.com/gaming-product/compressonator/)
* Intel ISPC compressors: [BC6H](https://software.intel.com/en-us/articles/fast-ispc-texture-compressor-update), [BC7](http://software.intel.com/en-us/articles/fast-ispc-texture-compressor)
[Intel Texture Works Plugin for Photoshop](https://github.com/GameTechDev/Intel-Texture-Works-Plugin)
@ -54,4 +55,4 @@ _Note that the NVIDIA tools haven't been updated in some time, and are currently
# Credits
The DirectXTex library is the work of Chuck Walbourn, with contributions from Matt Lee, Xin Huang, Craig Peeper, and the numerous other Microsoft engineers who developed the D3DX utility library over the years.
The DirectXTex library is the work of Chuck Walbourn, with contributions from Matt Lee, Xin Huang, Craig Peeper, and the numerous other Microsoft engineers who developed the D3DX utility library over the years.

6
Image-formats.md

@ -1,4 +1,4 @@
The DirectXTex library primarily uses [Windows Imaging Component](https://msdn.microsoft.com/en-us/library/windows/desktop/ee719654.aspx) (aka WIC) to perform image I/O, but includes a custom codec for ``DDS``, ``HDR``, and ``TGA`` files as well as optional support for ``EXR``. A complete, detailed description of image file formats is well beyond the scope of this wiki. This page does provide a quick overview of the comment formats the library deals with.
The DirectXTex library primarily uses [Windows Imaging Component](https://docs.microsoft.com/en-us/windows/desktop/wic/-wic-about-windows-imaging-codec) (aka WIC) to perform image I/O, but includes a custom codec for ``DDS``, ``HDR``, and ``TGA`` files as well as optional support for ``EXR``. A complete, detailed description of image file formats is well beyond the scope of this wiki. This page does provide a quick overview of the common formats the library is designed to read/write.
# BMP (Windows Bitmap Format)
The ``BMP`` file format is a long-lived Windows-specific format for images which is supported by a built-in WIC codec. See [Wikipedia](https://en.wikipedia.org/wiki/BMP_file_format) for more details.
@ -6,7 +6,7 @@ The ``BMP`` file format is a long-lived Windows-specific format for images which
To aid in debugging, here is a [simple console program](https://github.com/Microsoft/DirectXTex/wiki/bmpdump.cpp) for dumping out the content of a BMP header in a human-readable form.
# DDS (DirectDraw Surface)
The ``DDS`` file format is not so much an image format as a "Direct3D resource" container for textures. It can contain data in all DXGI formats, 1D textures, 2D textures, 1D & 2D texture arrays, cubemaps, cubemap arrays, and volume maps. For more details, see [The DDS File Format Lives](http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx) and [DDS Programmer's Guide](http://msdn.microsoft.com/en-us/library/bb943991.aspx).
The ``DDS`` file format is not so much an image format as a "Direct3D resource" container for textures. It can contain data in all DXGI formats, 1D textures, 2D textures, 1D & 2D texture arrays, cubemaps, cubemap arrays, and volume maps. For more details, see [The DDS File Format Lives](http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx) and [DDS Programmer's Guide](https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dx-graphics-dds-pguide).
> Windows 8.x and Windows 10 include a built-in WIC codec which supports ``DDS`` files in DXTn (aka BC1-BC3) format. No other formats are supported.
@ -28,7 +28,7 @@ The ``WDP`` file format (aka JPEG-XR) is a High-Dynamic Range (HDR) image file f
> Note that the Xbox One XDK version of WIC does not include the HD Photo codec.
# HDR (Radiance RGBE)
The ``HDR`` file format is a High-Dynamic Range (HDR) image file format, and is commonly used as a source for textures. See [Wikipedia](https://en.wikipedia.org/wiki/RGBE_image_format) for more details.
The ``HDR`` file format is a High-Dynamic Range (HDR) image file format, and is commonly used as a source for textures. See [Wikipedia](https://en.wikipedia.org/wiki/RGBE_image_format) for more details.
Greg Ward, "Real Pixels", *Graphics Gems II*, James Arvo (editor), Academic Press, 1991, ISBN: 0120644819, p. 80-83 ([code](http://www.realtimerendering.com/resources/GraphicsGems/gemsii/RealPixels/))

8
IsSupportedTexture.md

@ -1,8 +1,10 @@
Returns true if the given texture metadata is supported by the device.
Returns true if the given texture metadata describes a texture that is supported by the provided Direct3D device.
bool IsSupportedTexture( ID3D11Device* pDevice, const TexMetadata& metadata );
```cpp
bool IsSupportedTexture( ID3D11Device* pDevice, const TexMetadata& metadata );
bool IsSupportedTexture( ID3D12Device* pDevice, const TexMetadata& metadata );
bool IsSupportedTexture( ID3D12Device* pDevice, const TexMetadata& metadata );
```
# Remarks

32
PremultiplyAlpha.md

@ -2,12 +2,14 @@ This converts an image to using premultiplied alpha. The format and size are not
Note that the conversion to premultipled alpha is not fully reversible. For example if alpha is 0, then all the color information becomes 0.
HRESULT PremultiplyAlpha( const Image& srcImage, DWORD flags,
ScratchImage& image );
```cpp
HRESULT PremultiplyAlpha( const Image& srcImage, DWORD flags,
ScratchImage& image );
HRESULT PremultiplyAlpha( const Image* srcImages, size_t nimages,
const TexMetadata& metadata, DWORD flags,
ScratchImage& result );
HRESULT PremultiplyAlpha( const Image* srcImages, size_t nimages,
const TexMetadata& metadata, DWORD flags,
ScratchImage& result );
```
> **Breaking Change notice**: The _flags_ parameter was not present in the August 2013 and previous versions of DirectXTex.
@ -21,19 +23,21 @@ _flags_: Combination of options to apply
This controls color space transformation for conversions.
* *``TEX_PMALPHA_SRGB_IN``* Indicates the input format is the sRGB format. This is implied if using a ``DXGI_FORMAT_*_SRGB`` format
* *``TEX_PMALPHA_SRGB_OUT``* Indicates the output format is the sRGB format. This is implied if using a ``DXGI_FORMAT_*_SRGB`` format
* *``TEX_PMALPHA_SRGB``* This is the same as setting both ``TEX_PMALPHA_SRGB_IN`` and ``TEX_PMALPHA_SRGB_OUT``
* *``TEX_PMALPHA_SRGB``* This is the same as setting both ``TEX_PMALPHA_SRGB_IN`` and ``TEX_PMALPHA_SRGB_OUT``
# Example
ScratchImage srcImage;
```cpp
ScratchImage srcImage;
...
ScratchImage destImage;
hr = PremultiplyAlpha( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(), TEX_PMALPHA_DEFAULT, destImage );
if ( FAILED(hr) )
...
ScratchImage destImage;
hr = PremultiplyAlpha( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(), TEX_PMALPHA_DEFAULT, destImage );
if ( FAILED(hr) )
...
```
# Remarks
@ -41,7 +45,7 @@ This function does not operate directly on block compressed images. See [[Decomp
This function cannot operate directly on a planar format image. See [[ConvertToSinglePlane]] for a method for converting planar data to a format that is supported by this routine.
This is most useful for working with rendering that relies on premultiplied alpha blending (see [DirectXTK](http://go.microsoft.com/fwlink/?LinkId=248929)).
This is most useful for working with rendering that relies on premultiplied alpha blending (see _DirectX Tool Kit_ for [DX11](https://github.com/Microsoft/DirectXTK) / [DX12](https://github.com/Microsoft/DirectXTK12)).
# Related Links

72
Resize.md

@ -1,15 +1,17 @@
Resize an image or set of images.
**Note:** that if given a set of images, the resulting ScratchImage will always have mipLevels of 1 (i.e. any mipmaps from the original are discarded)
> If given a set of images, the resulting ScratchImage will always have mipLevels of 1 (i.e. any mipmaps from the original are discarded). You can generate mipmaps at the new size using [[GenerateMipMaps]] / [[GenerateMipMaps3D]].
HRESULT Resize( const Image& srcImage,
size_t width, size_t height, DWORD filter,
ScratchImage& image );
```cpp
HRESULT Resize( const Image& srcImage,
size_t width, size_t height, DWORD filter,
ScratchImage& image );
HRESULT Resize( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
size_t width, size_t height, DWORD filter,
ScratchImage& result );
HRESULT Resize( const Image* srcImages, size_t nimages,
const TexMetadata& metadata,
size_t width, size_t height, DWORD filter,
ScratchImage& result );
```
# Parameters
@ -21,36 +23,40 @@ If using ``TEX_FILTER_DEFAULT``, this routine will default to using FANT if usin
If you have a 2D array of pixel data of 640 x 480 in 32 bit-per-pixel BGRA format, this products a new image 320 x 200 in size:
Image image;
image.width = 640;
image.height = 480;
image.format = DXGI_FORMAT_B8G8R8A8_UNORM;
image.rowPitch = sizeof(DWORD) * 640;
image.slicePitch = sizeof(DWORD) * 640 * 480;
image.pixels = reinterpret_cast<const uint8_t*>( pixelData );
```cpp
Image image;
image.width = 640;
image.height = 480;
image.format = DXGI_FORMAT_B8G8R8A8_UNORM;
image.rowPitch = sizeof(DWORD) * 640;
image.slicePitch = sizeof(DWORD) * 640 * 480;
image.pixels = reinterpret_cast<const uint8_t*>( pixelData );
ScratchImage destImage;
hr = Resize( image, 320, 200, TEX_FILTER_DEFAULT, destImage );
if ( FAILED(hr) )
...
ScratchImage destImage;
hr = Resize( image, 320, 200, TEX_FILTER_DEFAULT, destImage );
if ( FAILED(hr) )
...
// result is auto img = destImage.GetImage(0,0,0); where
// img->width = 320, img->height = 200, img->format = DXGI_FORMAT_B8G8R8A8_UNORM;
// img->rowPitch = sizeof(DWORD) * 320, img->slicePitch = sizeof(DWORD) * 320 * 200
// img->pixels is the image data
// result is auto img = destImage.GetImage(0,0,0); where
// img->width = 320, img->height = 200, img->format = DXGI_FORMAT_B8G8R8A8_UNORM;
// img->rowPitch = sizeof(DWORD) * 320, img->slicePitch = sizeof(DWORD) * 320 * 200
// img->pixels is the image data
```
If you have an existing ``ScratchImage``, you can resize all the images in it via this function:
ScratchImage srcImage;
```cpp
ScratchImage srcImage;
...
ScratchImage destImage;
hr = Resize( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(),
100, 50, TEX_FILTER_DEFAULT, destImage );
if ( FAILED(hr) )
...
ScratchImage destImage;
hr = Resize( srcImage.GetImages(), srcImage.GetImageCount(),
srcImage.GetMetadata(),
100, 50, TEX_FILTER_DEFAULT, destImage );
if ( FAILED(hr) )
...
```
# Remarks
@ -65,5 +71,5 @@ This function is implemented with both WIC and non-WIC code paths. The WIC code
# Release Notes
* When resizing HDR images, be sure to stick with the default of ``TEX_FILTER_FANT`` when using WIC as the ``IWICBitmapScalar`` has limited supported for high bit-depth and extended range formats. By default, the DirectXTex library chooses to use non-WIC codepaths when resizing for > 8 color-depth images with LINEAR or CUBIC filtering, with sRGB images, with MIRROR/WRAP semantics, or when using TRIANGLE filtering. It will also select non-WIC paths when dealing with 16k textures that are too large for WIC.
* On Windows 10 Creators Update (16299) or later, WIC has better handling when using the ``IWICBitmapScalar``
with 10:10:10:2 and float16 formats. On older versions of Windows, it will return the results for these formats as 32bpp which is then reconverted to the target format but with a loss of precision. You may want to use ``TEX_FILTER_FORCE_NON_WIC`` if the results you are getting appear to be losing precision on older releases of Windows.
* On Windows 10 Creators Update (16299) or later, WIC has better handling when using the ``IWICBitmapScalar``
with 10:10:10:2 and float16 formats. On older versions of Windows, it will return the results for these formats as 32bpp which is then reconverted to the target format but with a loss of precision. You may want to use ``TEX_FILTER_FORCE_NON_WIC`` if the results you are getting appear to be losing precision on older releases of Windows.

9
Resources.md

@ -29,13 +29,13 @@ Gamefest 2010 - [Block Compression Smorgasbord](http://download.microsoft.com/do
[The DDS File Format Lives](http://blogs.msdn.com/b/chuckw/archive/2010/02/05/the-dds-file-format-lives.aspx)
# MSDN
[DDS Programmer's Guide](http://msdn.microsoft.com/en-us/library/bb943991.aspx)
[DDS Programmer's Guide](https://docs.microsoft.com/en-us/windows/desktop/direct3ddds/dx-graphics-dds-pguide)
[Compressed Texture Resources (Direct3D 9)](http://msdn.microsoft.com/en-us/library/bb204843.aspx)
[Compressed Texture Resources (Direct3D 9)](https://docs.microsoft.com/en-us/windows/desktop/direct3d9/compressed-texture-resources)
[Block Compression (Direct3D 10)](http://msdn.microsoft.com/en-us/library/bb694531.aspx)
[Block Compression (Direct3D 10)](https://docs.microsoft.com/en-us/windows/desktop/direct3d10/d3d10-graphics-programming-guide-resources-block-compression)
[Texture Block Compression in Direct3D 11](http://msdn.microsoft.com/en-us/library/windows/desktop/hh308955.aspx)
[Texture Block Compression in Direct3D 11](https://docs.microsoft.com/en-us/windows/desktop/direct3d11/texture-block-compression-in-direct3d-11)
# Block compression
[Understanding BCn Texture Compression Formats](http://www.reedbeta.com/blog/2012/02/12/understanding-bcn-texture-compression-formats/)
@ -72,4 +72,3 @@ BC5 algorithm from "Real-Time Normal Map DXT Compression" by JMP van Waveren & I
# Related KB articles
[KB2670838](http://support.microsoft.com/kb/2670838)

110
TGA-I-O-Functions.md

@ -1,29 +1,35 @@
The [Targa Truvision](http://en.wikipedia.org/wiki/Truevision_TGA) (``.TGA``) format is commonly used as a texture source file format in game development, but this format is not supported by any built-in WIC codec. These functions implement a simple reader and writer for this format.
# GetMetadataFromTGAMemory, GetMetadataFromTGAFile
Returns the _TexMetadata_ from a ``.TGA`` file.
Returns the _TexMetadata_ metadata from a ``.TGA`` file.
HRESULT GetMetadataFromTGAMemory( const void* pSource, size_t size,
TexMetadata& metadata );
```cpp
HRESULT GetMetadataFromTGAMemory( const void* pSource, size_t size,
TexMetadata& metadata );
HRESULT GetMetadataFromTGAFile( const wchar_t* szFile,
TexMetadata& metadata );
HRESULT GetMetadataFromTGAFile( const wchar_t* szFile,
TexMetadata& metadata );
```
# LoadFromTGAMemory, LoadFromTGAFile
Loads a ``.TGA`` file.
HRESULT LoadFromTGAMemory( const void* pSource, size_t size,
TexMetadata* metadata, ScratchImage& image );
```cpp
HRESULT LoadFromTGAMemory( const void* pSource, size_t size,
TexMetadata* metadata, ScratchImage& image );
HRESULT LoadFromTGAFile( const wchar_t* szFile,
TexMetadata* metadata, ScratchImage& image );
HRESULT LoadFromTGAFile( const wchar_t* szFile,
TexMetadata* metadata, ScratchImage& image );
```
# SaveToTGAMemory, SaveToTGAFile
Saves an image to a ``.TGA`` file.
HRESULT SaveToTGAMemory( const Image& image, Blob& blob );
```cpp
HRESULT SaveToTGAMemory( const Image& image, Blob& blob );
HRESULT SaveToTGAFile( const Image& image, const wchar_t* szFile );
HRESULT SaveToTGAFile( const Image& image, const wchar_t* szFile );
```
* ``R8G8B8A8_UNORM``, ``R8G8B8A8_UNORM_SRGB``, ``B8G8R8A8_UNORM``, and ``B8G8R8A8_UNORM_SRGB`` data are written as a 32-bit truecolor uncompressed ``.TGA`` file
@ -39,31 +45,37 @@ For the load functions, the _metadata_ parameter can be nullptr as this informat
# Examples
This is a simple loading example. The ``TGA`` format cannot contain complicated multi-image formats, so the _TexMetadata_ info is redundant information.
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromTGAFile( L"ROCKS.TGA", nullptr, *image );
if ( FAILED(hr) )
// error
```cpp
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromTGAFile( L"ROCKS.TGA", nullptr, *image );
if ( FAILED(hr) )
// error
```
A ``TGA`` file can only store one 2D image.
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToTGAFile( *img, L"NEW_IMAGE.TGA" );
if ( FAILED(hr) )
// error
```cpp
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToTGAFile( *img, L"NEW_IMAGE.TGA" );
if ( FAILED(hr) )
// error
```
You can also save data directly from memory without using the intermediate **ScratchImage** at all. This example assumes a single 2D image is being written out.
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<a DXGI format from the supported list above>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToTGAFile( img, L"NEW_IMAGE.TGA" );
if ( FAILED(hr) )
// error
```cpp
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<a DXGI format from the supported list above>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToTGAFile( img, L"NEW_IMAGE.TGA" );
if ( FAILED(hr) )
// error
```
# Implementation Notes
@ -76,36 +88,44 @@ You can also save data directly from memory without using the intermediate **Scr
# Windows Store apps
[File access and permissions (Windows Runtime apps)](https://msdn.microsoft.com/en-us/library/windows/apps/hh967755.aspx)
[File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions)
## Load
If you wish to load an image from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use LoadFromTGAFile on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
```cpp
// Using C++/CX (/ZW) and the Parallel Patterns Library (PPL)
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
if (file)
{
if (file)
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
{
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
if ( tempFile )
{
if ( tempFile )
{
HRESULT hr = LoadFromTGAFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
HRESULT hr = LoadFromTGAFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
});
}
```
## Save
For SaveToTGAFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```
If you are going to immediately copy it to another location via StorageFolder, then use the app's temporary folder:
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```
# Further reading

18
Texassemble.md

@ -1,6 +1,6 @@
This DirectXTex sample is a command-line texture utility for creating ``DDS`` files containing cubemaps, volume maps, or texture arrays created from individual images.
_This utility does not support mipmap generation or texture compression, but the resulting ``DDS`` file can be further processed by the [[Texconv]] utility. Any texture compressed input file is decompressed on load._
> This utility does not support mipmap generation or texture compression, but the resulting ``DDS`` file can be further processed by the [[Texconv]] utility. Any texture compressed input file is decompressed on load.
# Syntax
``Texassemble.exe`` uses the following command syntax:
@ -38,23 +38,23 @@ The file-name parameter indicates the file(s) to use to create the assembled ima
**gif**: Converts an animated ``gif`` into a texture array with properly composed frames.
# Optional Switches Description
# Optional Switches Description
**-r**: Input file names can contain wildcard characters (``?`` or ``*``). If this switch is used, subdirectories are also searched.
**-w _number_**: Width of the output texture in pixels.
**-h _number_**: Height of the output texture in pixels. If no size is given, the size is taken from the first input image.
**-h _number_**: Height of the output texture in pixels. If no size is given, the size is taken from the first input image.
**-f _format_**: Output format. Specify the DXGI format without the ``DXGI_FORMAT_`` prefix (i.e. ``-f R10G10B10A2_UNORM``). If no format is given, the format of the first image file is used.
**-f _format_**: Output format. Specify the DXGI format without the ``DXGI_FORMAT_`` prefix (i.e. ``-f R10G10B10A2_UNORM``). If no format is given, the format of the first image file is used.
**-if _filter_**: Image filter used for resizing the images. Use one of the following: ``POINT``, ``LINEAR``, ``CUBIC``, ``FANT``, ``BOX``, ``TRIANGLE``, ``POINT_DITHER``, ``LINEAR_DITHER``, ``CUBIC_DITHER``, ``FANT_DITHER``, ``BOX_DITHER``, ``TRIANGLE_DITHER``, ``POINT_DITHER_DIFFUSION``, ``LINEAR_DITHER_DIFFUSION``, ``CUBIC_DITHER_DIFFUSION``, ``FANT_DITHER_DIFFUSION``, ``BOX_DITHER_DIFFUSION``, or ``TRIANGLE_DITHER_DIFFUSION``. Filters with ``DITHER`` in their name indicate that the 4x4 ordered dither algorithm, while ``DITHER_DIFFUSION`` is error diffusion dithering.
**-if _filter_**: Image filter used for resizing the images. Use one of the following: ``POINT``, ``LINEAR``, ``CUBIC``, ``FANT``, ``BOX``, ``TRIANGLE``, ``POINT_DITHER``, ``LINEAR_DITHER``, ``CUBIC_DITHER``, ``FANT_DITHER``, ``BOX_DITHER``, ``TRIANGLE_DITHER``, ``POINT_DITHER_DIFFUSION``, ``LINEAR_DITHER_DIFFUSION``, ``CUBIC_DITHER_DIFFUSION``, ``FANT_DITHER_DIFFUSION``, ``BOX_DITHER_DIFFUSION``, or ``TRIANGLE_DITHER_DIFFUSION``. Filters with ``DITHER`` in their name indicate that the 4x4 ordered dither algorithm, while ``DITHER_DIFFUSION`` is error diffusion dithering.
**-srgb**, **-srgbi**, or **-srgbo**: Use sRGB if both the input and output data are in the sRGB color format (ie. gamma ~2.2). Use sRGBi if only the input is in sRGB; use sRGBo if only the output is in sRGB.
**-sepalpha**: Separates alpha channel for resize.
**-sepalpha**: Separates alpha channel for resize.
**-nowic**: Forces filtering to use non-WIC-based code paths. This is useful for working around known issues with WIC depending on which operating system you are using.
**-wrap**, **-mirror**: Sets the texture addressing mode for filtering to wrap or mirror, otherwise defaults to clamp.
**-wrap**, **-mirror**: Sets the texture addressing mode for filtering to wrap or mirror, otherwise defaults to clamp.
**-alpha**: Converts a premultiplied alpha image to non-premultiplied alpha (a.k.a. straight alpha).
@ -62,11 +62,11 @@ The file-name parameter indicates the file(s) to use to create the assembled ima
**-y**: overwrite existing output file if any. By default, the tool will abort if the output file already exists.
**-dx10**: Forces DDS file output to always use the "DX10" header extension, and allows the writing of alpha mode metadata information. The resulting file may not be compatible with the legacy D3DX10 or D3DX11 libraries.
**-dx10**: Forces DDS file output to always use the "DX10" header extension, and allows the writing of alpha mode metadata information. The resulting file may not be compatible with the legacy D3DX10 or D3DX11 libraries.
**-tonemap**: Applies [tonemap operator](http://www.cs.utah.edu/~reinhard/cdrom/) based on maximum luminosity to ensure HDR image data is adjusted to an LDR range.
**-nologo**: Suppress copyright message.
**-nologo**: Suppress copyright message.
**-flist _filename_**: Uses the provided filename as a text file containing a list of input files (one per line). Ignores lines that begin with ``#`` (used for comments). Does not support providing additional command-line arguments or the use of filename wildcards.

52
Texconv.md

@ -1,12 +1,12 @@
This DirectXTex sample is an implementation of the **texconv** command-line texture utility from the legacy DirectX SDK utilizing DirectXTex rather than D3DX. This tool loads an image and prepares it for runtime use by resizing, format conversion, mip-map generation, block-compression, and writes the result in a file format suited for runtime use. It can also be used for other image-to-image processing.
_To create cubemaps, volume maps, or texture arrays from individual files, use [[Texassemble]]_
> To create cubemaps, volume maps, or texture arrays from individual files, use [[Texassemble]].
# Syntax
``Texconv.exe`` uses the following command syntax:
texconv [-r] [-w number] [-h number] [-m number] [-f format]
[-if filter] [-srgb | -srgbi | -srgbo] [-ft file-type]
[-if filter] [-srgb | -srgbi | -srgbo] [-ft file-type]
[-px string] [-sx string] [-o directory] [-y]
[-hflip] [-vflip] [-sepalpha] [-nowic] [-wrap | -mirror]
[-pmalpha | -alpha] [-fl feature-level] [-pow2]
@ -22,7 +22,7 @@ _To create cubemaps, volume maps, or texture arrays from individual files, use [
The file-name parameter indicates the file(s) to convert using ``dds``, ``tga``, ``hdr``, or a WIC-supported format (``bmp``, ``jpg``, ``png``, ``jxr``, etc.).
# Optional Switches Description
# Optional Switches Description
**-r**: Input file names can contain wildcard characters (``?`` or ``*``). If this switch is used, subdirectories are also searched.
**-w _number_**: Width of the output texture in pixels.
@ -32,7 +32,7 @@ The file-name parameter indicates the file(s) to convert using ``dds``, ``tga``,
**-f _format_**: Output format. Specify the DXGI format without the ``DXGI_FORMAT_`` prefix (i.e. ``-f R10G10B10A2_UNORM``). It also supports some common aliases (``-f DXT1`` for ``DXGI_FORMAT_BC1_UNORM``, ``-f DXT5`` for ``DXGI_FORMAT_BC3_UNORM``, ``-f BGRA`` for ``DXGI_FORMAT_B8G8R8A8_UNORM``, ``-f FP16`` for ``DXGI_FORMAT_R16G16B16A16_FLOAT``, etc.)
**-if _filter_**: Image filter used for resizing the images. Use one of the following: ``POINT``, ``LINEAR``, ``CUBIC``, ``FANT``, ``BOX``, ``TRIANGLE``, ``POINT_DITHER``, ``LINEAR_DITHER``, ``CUBIC_DITHER``, ``FANT_DITHER``, ``BOX_DITHER``, ``TRIANGLE_DITHER``, ``POINT_DITHER_DIFFUSION``, ``LINEAR_DITHER_DIFFUSION``, ``CUBIC_DITHER_DIFFUSION``, ``FANT_DITHER_DIFFUSION``, ``BOX_DITHER_DIFFUSION``, or ``TRIANGLE_DITHER_DIFFUSION``. Filters with ``DITHER`` in their name indicate that the 4x4 ordered dither algorithm, while ``DITHER_DIFFUSION`` is error diffusion dithering.
**-if _filter_**: Image filter used for resizing the images. Use one of the following: ``POINT``, ``LINEAR``, ``CUBIC``, ``FANT``, ``BOX``, ``TRIANGLE``, ``POINT_DITHER``, ``LINEAR_DITHER``, ``CUBIC_DITHER``, ``FANT_DITHER``, ``BOX_DITHER``, ``TRIANGLE_DITHER``, ``POINT_DITHER_DIFFUSION``, ``LINEAR_DITHER_DIFFUSION``, ``CUBIC_DITHER_DIFFUSION``, ``FANT_DITHER_DIFFUSION``, ``BOX_DITHER_DIFFUSION``, or ``TRIANGLE_DITHER_DIFFUSION``. Filters with ``DITHER`` in their name indicate that the 4x4 ordered dither algorithm, while ``DITHER_DIFFUSION`` is error diffusion dithering.
**-srgb**, **-srgbi**, or **-srgbo**: Use sRGB if both the input and output data are in the sRGB color format (ie. gamma ~2.2). Use sRGBi if only the input is in sRGB; use sRGBo if only the output is in sRGB.
@ -46,14 +46,14 @@ The file-name parameter indicates the file(s) to convert using ``dds``, ``tga``,
* ``wdp``, ``hdp``, ``jxr``: Windows Media Photo
**-px _string_**: Text string to attach to the front of the resulting texture's name.
**-sx _string_**: Text string to attach to the end of the resulting texture's name.
**-sx _string_**: Text string to attach to the end of the resulting texture's name.
**-o _directory_**: Output directory.
**-o _directory_**: Output directory.
**-y**: overwrite existing output file if any. By default, the tool will skip the write if the output file already exists.
**-hflip**: Perform horizonal flip of image
**-vflip**: Perform horizonal flip of image
**-vflip**: Perform horizonal flip of image
**-sepalpha**: Separates alpha channel for resize/mipmap generation. This implies an alpha mode setting of ``DDS_ALPHA_MODE_CUSTOM`` as this is typically only used if the alpha channel doesn't contain transparency information.
@ -61,7 +61,7 @@ The file-name parameter indicates the file(s) to convert using ``dds``, ``tga``,
**-nowic**: Forces filtering to use non-WIC-based code paths. This is useful for working around known issues with WIC depending on which operating system you are using.
**-wrap**, **-mirror**: Sets the texture addressing mode for filtering to wrap or mirror, otherwise defaults to clamp.
**-wrap**, **-mirror**: Sets the texture addressing mode for filtering to wrap or mirror, otherwise defaults to clamp.
**-pmalpha**: Converts the final texture data to use premultiplied alpha. This sets an alpha mode of ``DDS_ALPHA_MODE_PREMULTIPLIED`` unless the entire alpha channel is fully opaque.
@ -72,7 +72,7 @@ The file-name parameter indicates the file(s) to convert using ``dds``, ``tga``,
**-pow2**: Fits each texture to a power-of-2 for width & height, minimizing changes to the aspect ratio. The maximum size for a dimension is based on the ``-fl`` switch (defaults to 16384).
**-tu**: DDS files with TYPELESS formats are treated as UNORM
**-tf**: DDS files with TYPELESS formats are treated as FLOAT
**-tf**: DDS files with TYPELESS formats are treated as FLOAT
> Generally typeless formats will fail most operations, so these options let you override the type.
@ -84,32 +84,32 @@ The file-name parameter indicates the file(s) to convert using ``dds``, ``tga``,
**-dx10**: Forces DDS file output to always use the "DX10" header extension, and allows the writing of alpha mode metadata information. The resulting file may not be compatible with the legacy D3DX10 or D3DX11 libraries.
**-nologo**: Suppress copyright message.
**-nologo**: Suppress copyright message.
**-flist _filename_**: Uses the provided filename as a text file containing a list of input files (one per line). Ignores lines that begin with ``#`` (used for comments). Does not support providing additional command-line arguments or the use of filename wildcards.
**-singleproc**: If the DirectXTex library and the texconv utility are built with OpenMP enabled, by default the tool will use multi-threading for CPU-based compression of BC6H and BC7 formats to spread the compression work across multiple cores. This flag disables this behavior forcing it to remain on a single core.
**-singleproc**: If the DirectXTex library and the texconv utility are built with OpenMP enabled, by default the tool will use multi-threading for CPU-based compression of BC6H and BC7 formats to spread the compression work across multiple cores. This flag disables this behavior forcing it to remain on a single core.
**-gpu** _adapterIndex_: When compressing BC6H / BC7 content, texconv will use DirectCompute on the GPU at the given index if available. The default is 0 which is the default adapter.
**-gpu** _adapterIndex_: When compressing BC6H / BC7 content, texconv will use DirectCompute on the GPU at the given index if available. The default is 0 which is the default adapter.
**-nogpu**: When compressing BC6H / BC7 content, texconv will use DirectCompute on the GPU if available. Use of this flag forces texconv to always use the software codec instead.
**-aw _number_**: Provides an alpha weighting to use with the error metric for the BC7 GPU compressor. Defaults to 1.0.
**-nmap**: flags Indicates conversion from a height-map to a normal-map. The flags is a combination of one or more of the following, and must have one of r, g, b, a, or l: r Use the red channel of the input as the height
* **g**: Use the green channel of the input as the height
* **b**: Use the blue channel of the input as the height
* **a**: Use the alpha channel of the input as the height
* **l**: Use the luminance computed from red, green, and blue channels of the input as the height
* **m**: Use mirroring in U & V. Defaults to wrap when doing the central difference computation.
* **u**: Use mirroring in U. Defaults to wrap when doing the central difference computation.
* **v**: Use mirroring in V. Defaults to wrap when doing the central difference computation.
* **i**: Invert sign of the computed normal
**-nmap**: flags Indicates conversion from a height-map to a normal-map. The flags is a combination of one or more of the following, and must have one of r, g, b, a, or l: r Use the red channel of the input as the height
* **g**: Use the green channel of the input as the height
* **b**: Use the blue channel of the input as the height
* **a**: Use the alpha channel of the input as the height
* **l**: Use the luminance computed from red, green, and blue channels of the input as the height
* **m**: Use mirroring in U & V. Defaults to wrap when doing the central difference computation.
* **u**: Use mirroring in U. Defaults to wrap when doing the central difference computation.
* **v**: Use mirroring in V. Defaults to wrap when doing the central difference computation.
* **i**: Invert sign of the computed normal
* **o**: Compute a rough occlusion term and encode it into the alpha channel of the output.
**-nmapamp _number_**: Indicates an amplitude for the normal map, which defaults to 1.
**-bcuniform** Uses uniform weighting rather than perceptual (BC1-BC3)
**-bcuniform** Uses uniform weighting rather than perceptual (BC1-BC3)
**-bcmax** Uses maximum compression (BC7: enables mode 0 & 2 usage)
@ -149,7 +149,7 @@ Open a [Command Prompt](http://windows.microsoft.com/en-us/windows/command-promp
Enter the following command-line after changing to the appropriate directory:
texconv -pow2 -f BC1_UNORM cat.jpg
texconv -pow2 -f BC1_UNORM cat.jpg
This loads a JPEG image 'cat.jpg', resizes the image to a power of 2 in each dimension (if the original was 512 x 683 it is resized to 256 x 512), mipmaps are generated, the file is converted to ``DXGI_FORMAT_BC1_UNORM`` (aka DXT1) block compression, and written out as 'cat.dds'.
@ -165,7 +165,7 @@ This loads the PNG image 'heightmap.png', converts it to a normal-map using lumi
This loads the HDR (Radiance RGBE) image `myimage.hdr`, performs a tone-mapping operation, and then writes the result to `myimage.bmp`.
texconv -pow2 -fl 9.3 -f BC3_UNORM -m 1 *.bmp
texconv -pow2 -fl 9.3 -f BC3_UNORM -m 1 *.bmp
This creates a ``DDS`` file for each ``BMP`` file in the current directory that is sized to a power-of-2 respecting aspect ratio with a maximum size of 4096 for a given dimension. The results are compressed as ``DXGI_FORMAT_BC3_UNORM`` (a.k.a. DXT5) and have no mipmaps.
@ -173,4 +173,4 @@ This creates a ``DDS`` file for each ``BMP`` file in the current directory that
When loading ``BMP`` files, if the WIC codec fails to load the image, the _texconv_ tool will check to see if it's an [Extended BMP](http://www.mwgfx.co.uk/NewBmp/tech.htm) containing ``DXT1``, ``DXT3``, or ``DXT5`` compressed data. The tool does not support writing Extended BMP files. Typically you need to use ``-vflip`` with such files as well.
Support for [OpenEXR](http://www.openexr.com/) (``EXR``) can be added to the *texconv* utility. Uncomment ``#define USE_OPENEXR`` in the source, and add the DirectXTex auxiliary module to the project. See [[Adding OpenEXR]] for more details including building the OpenEXR library.
Support for [OpenEXR](http://www.openexr.com/) (``EXR``) can be added to the *texconv* utility. Uncomment ``#define USE_OPENEXR`` in the source, and add the DirectXTex auxiliary module to the project. See [[Adding OpenEXR]] for more details including building the OpenEXR library.

148
TransformImage.md

@ -1,20 +1,22 @@
Creates a new image by executing a user-supplied function across an input image.
HRESULT TransformImage(
const Image& image,
std::function<
void(XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
> pixelFunc,
ScratchImage& result );
```cpp
HRESULT TransformImage(
const Image& image,
std::function<
void(XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
> pixelFunc,
ScratchImage& result );
HRESULT TransformImage(
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
std::function<
void(XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
> pixelFunc,
ScratchImage& result );
HRESULT TransformImage(
const Image* srcImages, size_t nimages, const TexMetadata& metadata,
std::function<
void(XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
> pixelFunc,
ScratchImage& result );
```
**Breaking change notice:** The first release of this function was ``Transform`` but this generic name can cause conflicts in some client code so it was renamed ``TransformImage``.
> **Breaking change notice:** In the September 2016 release this function was ``Transform`` but this generic name can cause conflicts in some client code so it was renamed ``TransformImage``.
# Parameters
@ -23,78 +25,82 @@ _pixelFunc_: A callback function to invoke for each scanline of the image which
# Example
This function performs a colorkey or [chromakey](https://en.wikipedia.org/wiki/Chroma_key) transformation setting alpha to 0 (transparent) wherever the color is found and 1 (opaque) otherwise.
ScratchImage result;
hr = TransformImage(image->GetImages(), image->GetImageCount(), image->GetMetadata(),
[](XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
```cpp
ScratchImage result;
hr = TransformImage(image->GetImages(), image->GetImageCount(), image->GetMetadata(),
[](XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
{
static const XMVECTORF32 s_chromaKey = { 0.f, 1.f, 0.f, 0.f };
static const XMVECTORF32 s_tolerance = { 0.2f, 0.2f, 0.2f, 0.f };
UNREFERENCED_PARAMETER(y);
for (size_t j = 0; j < width; ++j)
{
static const XMVECTORF32 s_chromaKey = { 0.f, 1.f, 0.f, 0.f };
static const XMVECTORF32 s_tolerance = { 0.2f, 0.2f, 0.2f, 0.f };
XMVECTOR value = inPixels[j];
UNREFERENCED_PARAMETER(y);
for (size_t j = 0; j < width; ++j)
if (XMVector3NearEqual(value, s_chromaKey, s_tolerance))
{
XMVECTOR value = inPixels[j];
if (XMVector3NearEqual(value, s_chromaKey, s_tolerance))
{
value = g_XMZero;
}
else
{
value = XMVectorSelect(g_XMOne, value, g_XMSelect1110);
}
outPixels[j] = value;
}
}, result);
if (FAILED(hr))
...
value = g_XMZero;
}
else
{
value = XMVectorSelect(g_XMOne, value, g_XMSelect1110);
}
outPixels[j] = value;
}
}, result);
if (FAILED(hr))
...
```
Here is an example for applying a [tonemap operator](http://www.cs.utah.edu/~reinhard/cdrom/):
XMVECTOR maxLum = XMVectorZero();
HRESULT hr = EvaluateImage(*image.GetImage(0, 0, 0),
[&](const XMVECTOR* pixels, size_t width, size_t y)
{
UNREFERENCED_PARAMETER(y);
for (size_t j = 0; j < width; ++j)
{
static const XMVECTORF32 s_luminance = { 0.3f, 0.59f, 0.11f, 0.f };
XMVECTOR v = *pixels++;
v = XMVector3Dot(v, s_luminance);
maxLum = XMVectorMax(v, maxLum);
}
});
if (FAILED(hr))
...
maxLum = XMVectorMultiply(maxLum, maxLum);
ScratchImage result;
hr = TransformImage(image->GetImages(), image->GetImageCount(), image->GetMetadata(),
[](XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
```cpp
XMVECTOR maxLum = XMVectorZero();
HRESULT hr = EvaluateImage(*image.GetImage(0, 0, 0),
[&](const XMVECTOR* pixels, size_t width, size_t y)
{
UNREFERENCED_PARAMETER(y);
for (size_t j = 0; j < width; ++j)
{
XMVECTOR value = inPixels[j];
static const XMVECTORF32 s_luminance = { 0.3f, 0.59f, 0.11f, 0.f };
XMVECTOR scale = XMVectorDivide(
XMVectorAdd(g_XMOne, XMVectorDivide(value, maxLum)),
XMVectorAdd(g_XMOne, value));
XMVECTOR nvalue = XMVectorMultiply(value, scale);
XMVECTOR v = *pixels++;
value = XMVectorSelect(value, nvalue, g_XMSelect1110);
v = XMVector3Dot(v, s_luminance);
outPixels[j] = value;
maxLum = XMVectorMax(v, maxLum);
}
}, result);
if (FAILED(hr))
...
});
if (FAILED(hr))
...
maxLum = XMVectorMultiply(maxLum, maxLum);
ScratchImage result;
hr = TransformImage(image->GetImages(), image->GetImageCount(), image->GetMetadata(),
[](XMVECTOR* outPixels, const XMVECTOR* inPixels, size_t width, size_t y)
{
UNREFERENCED_PARAMETER(y);
for (size_t j = 0; j < width; ++j)
{
XMVECTOR value = inPixels[j];
XMVECTOR scale = XMVectorDivide(
XMVectorAdd(g_XMOne, XMVectorDivide(value, maxLum)),
XMVectorAdd(g_XMOne, value));
XMVECTOR nvalue = XMVectorMultiply(value, scale);
value = XMVectorSelect(value, nvalue, g_XMSelect1110);
outPixels[j] = value;
}
}, result);
if (FAILED(hr))
...
```
# Remarks
The user-supplied function always reads & writes ``DXGI_FORMAT_R32G32B32A32_FLOAT`` data in the scanlines.

242
WIC-I-O-Functions.md

@ -1,49 +1,55 @@
These functions use the Windows Imaging Component (WIC) to read or write an image file. There are built-in WIC codecs in Windows for ``.BMP``, ``.PNG``, ``.GIF``, ``.TIFF``, ``.JPEG``, and JPEG-XR / HD Photo images. Some containers (``.GIF`` and ``.TIFF``) can contain multi-frame bitmaps files.
# GetMetadataFromWICMemory, GetMetadataFromWICFile
Returns the _TexMetadata_ from a WIC-supported bitmap file.
Returns the _TexMetadata_ metadata from a WIC-supported bitmap file.
HRESULT GetMetadataFromWICMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata& metadata,
std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );
```cpp
HRESULT GetMetadataFromWICMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata& metadata,
std::function<void(IWICMetadataQueryReader*)> getMQR = nullptr );
HRESULT GetMetadataFromWICFile( const wchar_t* szFile,
DWORD flags, TexMetadata& metadata,
std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );
HRESULT GetMetadataFromWICFile( const wchar_t* szFile,
DWORD flags, TexMetadata& metadata,
std::function<void(IWICMetadataQueryReader*)> getMQR = nullptr );
```
# LoadFromWICMemory, LoadFromWICFile
Loads a WIC-supported bitmap file.
HRESULT LoadFromWICMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata* metadata, ScratchImage& image,
std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );
```cpp
HRESULT LoadFromWICMemory( const void* pSource, size_t size,
DWORD flags, TexMetadata* metadata, ScratchImage& image,
std::function<void(IWICMetadataQueryReader*)> getMQR = nullptr );
HRESULT LoadFromWICFile( const wchar_t* szFile,
DWORD flags, TexMetadata* metadata, ScratchImage& image,
std::function<void DIRECTX_STD_CALLCONV(IWICMetadataQueryReader*)> getMQR = nullptr );
HRESULT LoadFromWICFile( const wchar_t* szFile,
DWORD flags, TexMetadata* metadata, ScratchImage& image,
std::function<void(IWICMetadataQueryReader*)> getMQR = nullptr );
```
# SaveToWICMemory, SaveToWICFile
Saves a single image or a set of images to a WIC-supported bitmap file. The caller provides the desired WIC container format to use via _guidContainerFormat_ (see [[GetWICCodec]] for a helper). There is an optional _targetFormat_ to specify a desired WIC pixel format (which will result in an ``E_FAIL`` if not supported by the WIC codec)
HRESULT SaveToWICMemory( const Image& image,
DWORD flags, REFGUID guidContainerFormat,
Blob& blob, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
```cpp
HRESULT SaveToWICMemory( const Image& image,
DWORD flags, REFGUID guidContainerFormat,
Blob& blob, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
HRESULT SaveToWICMemory( const Image* images, size_t nimages,
DWORD flags, REFGUID guidContainerFormat,
Blob& blob, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
HRESULT SaveToWICMemory( const Image* images, size_t nimages,
DWORD flags, REFGUID guidContainerFormat,
Blob& blob, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
HRESULT SaveToWICFile( const Image& image,
DWORD flags, REFGUID guidContainerFormat,
const wchar_t* szFile, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
HRESULT SaveToWICFile( const Image& image,
DWORD flags, REFGUID guidContainerFormat,
const wchar_t* szFile, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
HRESULT SaveToWICFile( const Image* images, size_t nimages,
DWORD flags, REFGUID guidContainerFormat,
const wchar_t* szFile, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
HRESULT SaveToWICFile( const Image* images, size_t nimages,
DWORD flags, REFGUID guidContainerFormat,
const wchar_t* szFile, const GUID* targetFormat = nullptr,
std::function<void(IPropertyBag2*)> setCustomProps = nullptr );
```
# Parameters
For the load functions, the _metadata_ parameter can be nullptr as this information is also available in the returned **ScratchImage**.
@ -56,88 +62,100 @@ For the saving functions, _setCustomProps_ is an optional callback. If it is non
This is a simple loading example. Since it only returns a single 2D image, the _TexMetadata_ info is redundant information.
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromWICFile( L"WINLOGO.BMP", WIC_FLAGS_NONE, nullptr, *image );
if ( FAILED(hr) )
// error
```cpp
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromWICFile( L"WINLOGO.BMP", WIC_FLAGS_NONE, nullptr, *image );
if ( FAILED(hr) )
// error
```
This is a multi-image loading example which can load an array of 2D images.
TexMetadata info;
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromDDSFile( L"MULTIFRAME.TIF",
WIC_FLAGS_ALL_FRAMES, &info, *image );
if ( FAILED(hr) )
// error
```cpp
TexMetadata info;
auto image = std::make_unique<ScratchImage>();
HRESULT hr = LoadFromDDSFile( L"MULTIFRAME.TIF",
WIC_FLAGS_ALL_FRAMES, &info, *image );
if ( FAILED(hr) )
// error
```
Here we provide an optional callback to check for the [System.Photo.Orientation](https://msdn.microsoft.com/en-us/library/windows/desktop/bb760505.aspx) metadata query property:
Here we provide an optional callback to check for the [System.Photo.Orientation](https://docs.microsoft.com/en-us/windows/desktop/properties/props-system-photo-orientation) metadata query property:
TexMetadata info;
auto image = std::make_unique<ScratchImage>();
uint16_t orientation = 1;
HRESULT hr = LoadFromWICFile( L"Image.JPG", WIC_FLAGS_NONE, &info, *image,
[&](IWICMetadataQueryReader* reader)
{
PROPVARIANT value;
PropVariantInit( &value );
```cpp
TexMetadata info;
auto image = std::make_unique<ScratchImage>();
uint16_t orientation = 1;
HRESULT hr = LoadFromWICFile( L"Image.JPG", WIC_FLAGS_NONE, &info, *image,
[&](IWICMetadataQueryReader* reader)
{
PROPVARIANT value;
PropVariantInit( &value );
if ( SUCCEEDED(reader->GetMetadataByName( L"System.Photo.Orientation", &value ) )
&& value.vt == VT_UI2 )
{
orientation = value.uiVal;
}
if ( SUCCEEDED(reader->GetMetadataByName( L"System.Photo.Orientation", &value ) )
&& value.vt == VT_UI2 )
{
orientation = value.uiVal;
}
PropVariantClear( &value );
} );
if ( FAILED(hr) )
// error
PropVariantClear( &value );
} );
if ( FAILED(hr) )
// error
```
This is saving a simple 2D image to a specific file container. You can either use the WIC GUID directly or make use of the [[GetWICCodec]] helper. Keep in mind that WIC may convert the pixel format in the final output image, so there is an optional additional parameter you can use to request a specific storage pixel format. In this case, we want the file's pixel format to be an 8-bit per channel RGB without an alpha channel.
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToWICFile( *img, WIC_FLAGS_NONE,
GUID_ContainerFormatPng, L"NEW_IMAGE.PNG", &GUID_WICPixelFormat24bppBGR );
if ( FAILED(hr) )
// error
```cpp
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToWICFile( *img, WIC_FLAGS_NONE,
GUID_ContainerFormatPng, L"NEW_IMAGE.PNG", &GUID_WICPixelFormat24bppBGR );
if ( FAILED(hr) )
// error
```
You can also save data directly from memory without using the intermediate **ScratchImage** at all. This example assumes a single 2D image is being written out since a JPG file cannot contain an image array.
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<a DXGI format that maps directly to a WIC supported format>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToWICFile( img, WIC_FLAGS_NONE, GetWICCodec(WIC_CODEC_JPEG),
L"NEW_IMAGE.PNG" );
if ( FAILED(hr) )
// error
```cpp
Image img;
img.width = /*<width of pixel data>*/;
img.height = /*<height of pixel data>*/;
img.format = /*<a DXGI format that maps directly to a WIC supported format>*/;
img.rowPitch = /*<number of bytes in a scanline of the source data>*/;
img.slicePitch = /*<number of bytes in the entire 2D image>*/;
img.pixels = /*<pointer to pixel data>*/;
HRESULT hr = SaveToWICFile( img, WIC_FLAGS_NONE, GetWICCodec(WIC_CODEC_JPEG),
L"NEW_IMAGE.PNG" );
if ( FAILED(hr) )
// error
```
When writing WIC files, you can also provide a callback for setting specific encoding options.
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToWICFile( *img, WIC_FLAGS_NONE,
GUID_ContainerFormatTiff, L"NEW_IMAGE.TIF", nullptr,
[&](IPropertyBag2* props)
{
PROPBAG2 options[2] = { 0, 0 };
options[0].pstrName = L"CompressionQuality";
options[1].pstrName = L"TiffCompressionMethod";
```cpp
const Image* img = image->GetImage(0,0,0);
assert( img );
HRESULT hr = SaveToWICFile( *img, WIC_FLAGS_NONE,
GUID_ContainerFormatTiff, L"NEW_IMAGE.TIF", nullptr,
[&](IPropertyBag2* props)
{
PROPBAG2 options[2] = { 0, 0 };
options[0].pstrName = L"CompressionQuality";
options[1].pstrName = L"TiffCompressionMethod";
VARIANT varValues[2];
varValues[0].vt = VT_R4;
varValues[0].fltVal = 0.75f;
VARIANT varValues[2];
varValues[0].vt = VT_R4;
varValues[0].fltVal = 0.75f;
varValues[1].vt = VT_UI1;
varValues[1].bVal = WICTiffCompressionNone;
varValues[1].vt = VT_UI1;
varValues[1].bVal = WICTiffCompressionNone;
(void)props->Write( 2, options, varValues );
});
if ( FAILED(hr) )
// error
(void)props->Write( 2, options, varValues );
});
if ( FAILED(hr) )
// error
```
# Related Flags
* ``WIC_FLAGS_NONE`` Default flags.
@ -171,7 +189,7 @@ These flags control the use of interpolation modes for image conversions/resizin
* JPEG-XR / HD Photo supports nearly all WIC pixel formats including floating-point for both encoding and decoding.
* ``TIFF`` can contain floating-point data (128bpp or 96bpp), but the WIC built-in codec can only decode such images. It always converts floating-point data to unorm when encoding. Windows 7 incorrectly handles decoding 96bpp ``TIFF`` files, which is corrected with WIC2 by returning the new format ``GUID_WICPixelFormat96bppRGBFloat``
* ``TIFF`` can contain floating-point data (128bpp or 96bpp), but the WIC built-in codec can only decode such images. It always converts floating-point data to unorm when encoding. Windows 7 incorrectly handles decoding 96bpp ``TIFF`` files, which is corrected with WIC2 by returning the new format ``GUID_WICPixelFormat96bppRGBFloat``
* Windows WIC codec for ``.BMP`` files does not support alpha channels for 16-bit files. For 32-bit files, the alpha channel is ignored by Windows 7 or earlier. The WIC2 ``BMP`` codec can read 32-bit alpha channels if using the ``BITMAPV5HEADER`` header. DirectXTex opts into the WIC2 behavior for writing 32-bit alpha channels using the V5 header when available
@ -192,31 +210,41 @@ See [Windows Imaging Component and Windows 8](http://blogs.msdn.com/b/chuckw/arc
# Windows Store apps
[File access and permissions (Windows Runtime apps)](https://docs.microsoft.com/en-us/windows/uwp/files/file-access-permissions)
## Load
If you wish to load an image from a file that is specified by the user from a WinRT picker, you will need to copy the file locally to a temporary location before you can use LoadFromWICFile on it. This is because you either won't have file access rights to the user's file location, or the StorageFile is actually not a local file system path (i.e. it's a URL).
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
```cpp
// Using C++/CX (/ZW) and the Parallel Patterns Library (PPL)
create_task(openPicker->PickSingleFileAsync()).then([this](StorageFile^ file)
{
if (file)
{
if (file)
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
{
auto tempFolder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
create_task(file->CopyAsync( tempFolder, file->Name, NameCollisionOption::GenerateUniqueName )).then([this](StorageFile^ tempFile)
if ( tempFile )
{
if ( tempFile )
{
HRESULT hr = LoadFromWICFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
HRESULT hr = LoadFromWICFile( ..., tempFile->Path->Data(), ... );
DX::ThrowIfFailed(hr);
}
});
});
}
```
## Save
For SaveToWICFile to succeed, the application must have write access to the destination path. For Windows Store apps, the file access permissions are rather restricted so you'll need to make sure you use a fully qualified path to a valid write folder. A good location to use is the app data folder:
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->LocalFolder;
// use folder->Path->Data() as the path base
```
If you are going to immediately copy it to another location via StorageFolder, then use the app's temporary folder:
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```cpp
auto folder = Windows::Storage::ApplicationData::Current->TemporaryFolder;
// use folder->Path->Data() as the path base
```