git.cworth.org Git - apitrace/blob - thirdparty/directxtex/ReadMe.txt

   1 DIRECTX TEXTURE LIBRARY (DirectXTex)
   2 ------------------------------------
   3
   4 Copyright (c) Microsoft Corporation. All rights reserved.
   5
   6 November 15, 2012
   7
   8 This package contains DirectXTex, a shared source library for reading and writing DDS
   9 files, and performing various texture content processing operations including
  10 resizing, format conversion, mip-map generation, block compression for Direct3D runtime
  11 texture resources, and height-map to normal-map conversion. This library makes
  12 use of the Windows Image Component (WIC) APIs. It also includes a simple .TGA reader and
  13 writer since this image file format is commonly used for texture content processing pipelines,
  14 but is not currently supported by a built-in WIC codec.
  15
  16 The source is written for Visual C++ 2010 using the Direct3D headers from either
  17 a current DirectX SDK or Windows SDK. It can also be compiled using Visual Studio 2012 and the
  18 Windows SDK 8.0 headers.
  19
  20 It is recommended that you make use of Visual C++ 2010 Service Pack 1 or VS 2012, and
  21 Windows 7 Service Pack 1 or Windows 8.
  22
  23 DDSTextureLoader\
  24     This contains a streamlined version of the DirectX SDK sample DDSWithoutD3DX11 texture
  25     loading code for a simple light-weight runtime DDS loader. This version only supports
  26     Direct3D 11 and performs no runtime pixel data conversions (i.e. 24bpp legacy DDS files
  27     always fail). This is ideal for runtime usage, and supports the full complement of
  28     Direct3D 11 texture resources (1D, 2D, volume maps, cubemaps, mipmap levels,
  29     texture arrays, BC formats, etc.).
  30
  31 WICTextureLoader\
  32     This contains a Direct3D 11 2D texture loader that uses WIC to load a bitmap
  33     (BMP, JPEG, PNG, HD Photo, or other WIC supported file container), resize if needed
  34     based on the current feature level (or by explicit parameter), format convert to a
  35     DXGI_FORMAT if required, and then create a 2D texture. Furthermore, if a Direct3D 11
  36     device context is provided and the current device supports it for the given pixel format,
  37     it will auto-generate mipmaps. Note this does not support 1D textures, volume textures,
  38     cubemaps, or texture arrays. DDSTextureLoader is recommended for fully "precooked" textures
  39     for maximum performance and image quality, but this loader can be useful for creating
  40     simple 2D texture from standard image files at runtime.
  41
  42     Note: This function is not thread-safe if given a non-NULL device context for the auto-gen
  43     mip-map support.
  44
  45 DirectXTex\
  46     This contains the DirectXTex library. This includes a full-featured DDS reader and writer
  47     including legacy format conversions, a TGA reader and writer, a WIC-based bitmap reader and
  48     writer (BMP, JPEG, PNG, TIFF, and HD Photo), and various texture processing functions. This
  49     is intended primarily for tool usage.
  50
  51     Note that the majority of the header files here are intended for internal implementation
  52     of the library only (BC.h, DDS.h, DirectXTexP.h, and scoped.h). Only DirectXTex.h is
  53     meant as a 'public' header for the library.
  54
  55 Texconv\
  56     This DirectXTex sample is an implementation of the "texconv" command-line texture utility
  57     from the DirectX SDK utilizing DirectXTex rather than D3DX.
  58
  59     It supports the same arguments as the Texture Conversion Tool Extended (texconvex.exe) DirectX
  60     SDK utility. See <http://msdn.microsoft.com/en-us/library/ee422506.aspx>. The primary differences
  61     are the -10 and -11 arguments are not applicable; the filter names (POINT, LINEAR, CUBIC,
  62     FANT, POINT_DITHER, LINEAR_DITHER, CUBIC_DITHER, FANT_DITHER); and support for the .TGA file format.
  63     This also includes support for JPEG XR/HD Photo bitmap formats (see
  64     <http://blogs.msdn.com/b/chuckw/archive/2011/01/19/known-issue-texconvex.aspx>)
  65
  66 DDSView\
  67     This DirectXTex sample is a simple Direct3D 11-based viewer for DDS files. For array textures
  68     or volume maps, the "<" and ">" keyboard keys will show different images contained in the DDS.
  69     The "1" through "0" keys can also be used to jump to a specific image index.
  70
  71 XNAMath\
  72     This contains a copy of XNA Math version 2.05, which is an updated version of the library. This is
  73     required if building content with USE_XNAMATH (the default for the VS 2010 projects). The VS 2012
  74     projects use DirectXMath in the Windows SDK 8.0 instead.
  75     For details see
  76     <http://blogs.msdn.com/b/chuckw/archive/2012/06/22/xna-math-version-2-05-smoothing-the-transition-to-directxmath.aspx>
  77
  78 All content and source code for this package except XNA Math are bound to the Microsoft Public License (Ms-PL)
  79 <http://www.microsoft.com/en-us/openness/licenses.aspx#MPL>. The XNA Math library is subject
  80 to the DirectX SDK (June 2010) End-User License Agreement.
  81
  82 http://go.microsoft.com/fwlink/?LinkId=248926
  83
  84
  85 ------------------------------------
  86 RELEASE NOTES
  87
  88 * The DirectXTex library does not support block compression or decompression of mipmapped non-power-of-2 textures,
  89   although DDSTextureLoader will load these files correctly if the underlying device supports it.
  90
  91 * The DirectXTex library only supports CLAMP filtering, and does not yet support MIRROR or WRAP filtering
  92   (WIC operations only support CLAMP filtering).
  93
  94 * The DirectXTex library only supports box and POINT filtering, and does not support LINEAR or CUBIC filtering,
  95   for 3D volume mipmap-generation.
  96
  97 * Due to the underlying Windows BMP WIC codec, alpha channels are not supported for 16bpp or 32bpp BMP pixel format files. The Windows 8
  98   version of the Windows BMP WIC codec does support 32bpp pixel formats with alpha when using the BITMAPV5HEADER file header. Note the updated
  99   WIC is available on Windows 7 SP1 with KB 2670838 installed.
 100
 101 * The WIC conversion cases currently ignore TEX_FILTER_SRGB_IN and TEX_FILTER_SRGB_OUT out.
 102
 103 * For the DXGI 1.1 version of DirectXTex, 4:4:4:4 pixel format DDS files are always expanded to 8:8:8:8 upon load since DXGI 1.0
 104   and DXGI 1.1 versions of Direct3D do not support these resource formats. The DXGI 1.2 versions of DirectXTex and DDSTextureLoader
 105   make use of the DXGI_FORMAT_B4G4R4A4_UNORM format instead.
 106
 107 * 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)
 108   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,
 109   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). The DXGI 1.2 version of WICTextureLoader
 110   will load 16bpp pixel images as 5:6:5 or 5:5:5:1 rather than expand them to 32bpp RGBA.
 111
 112 * WICTextureLoader cannot load .TGA files unless the system has a 3rd party WIC codec installed. You must use the DirectXTex
 113   library for TGA file format support without relying on an add-on WIC codec.
 114
 115 * 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
 116   KB 2670838 installed.
 117
 118
 119 ------------------------------------
 120 RELEASE HISTORY
 121
 122 November 15, 2012
 123     Added support for WIC2 when available on Windows 8 and Windows 7 with KB 2670838
 124     Added optional targetGUID parameter to SaveWIC* APIs to influence final container pixel format choice
 125     Fixed bug in SaveDDS* which was generating invalid DDS files for 1D dimension textures
 126     Improved robustness of CaptureTexture when resolving MSAA source textures
 127     Sync'd DDSTextureLoader, ScreenGrab, and WICTextureLoader standalone versions with latest DirectXTK release
 128
 129 September 28, 2012
 130     Added ScreenGrab module for creating runtime screenshots
 131     Renamed project files for better naming consistency
 132     New Typeless utilities for DirectXTex
 133     Some minor code cleanup for DirectXTex's WIC writer function
 134     Bug fixes and new -tu/-tf options for texconv
 135
 136 June 22, 2012
 137     Moved to using XNA Math 2.05 instead of XNA Math 2.04 for USE_XNAMATH builds
 138     Fixed BGR vs. RGB color channel swizzle problem with 24bpp legacy .DDS files in DirectXTex
 139     Update to DirectXTex WIC and WICTextureLoader for additional 96bpp float format handling on Windows 8
 140
 141 May 31, 2012
 142     Minor fix for DDSTextureLoader's retry fallback that can happen with 10level9 feature levels
 143     Switched to use "_DEBUG" instead of "DEBUG" and cleaned up debug warnings
 144     added Metro style application project files for DirectXTex
 145
 146 April 20, 2012
 147     DirectTex's WIC-based writer opts-in for the Windows 8 BMP encoder option for writing 32 bpp RGBA files with the BITMAPV5HEADER
 148
 149 March 30, 2012
 150     WICTextureLoader updated with Windows 8 WIC pixel formats
 151     DirectXTex updated with limited non-power-of-2 texture support and TEX_FILTER_SEPARATE_ALPHA option
 152     Texconv updated with '-sepalpha' command-line option
 153     Added USE_XNAMATH control define to build DirectXTex using either XNAMath or DirectXMath
 154     Added VS 2012 project files (which use DirectXMath instead of XNAMath and define DXGI_1_2_FORMATS)
 155
 156 March 15, 2012
 157     Fix for resource leak in CreateShaderResourceView() Direct3D 11 helper function in DirectXTex
 158
 159 March 5, 2012
 160     Fix for too much temp memory allocated by WICTextureLoader; cleaned up legacy 'min/max' macro usage in DirectXTex
 161
 162 February 21, 2012
 163     WICTextureLoader updated to handle systems and device drivers without BGRA or 16bpp format support
 164
 165 February 20, 2012
 166     Some code cleanup for DirectXTex and DDSTextureLoader
 167     Fixed bug in 10:10:10:2 format fixup in the LoadDDSFromMemory function
 168     Fixed bugs in "non-zero alpha" special-case handling in LoadTGAFromFile
 169     Fixed bug in _SwizzleScanline when copying alpha channel for BGRA<->RGBA swizzling
 170
 171 February 11, 2012
 172     Update of DDSTextureLoader to also build in Metro style apps; added WICTextureLoader
 173     Added CMYK WIC pixel formats to the DirectXTex conversion table
 174
 175 January 30, 2012
 176     Minor code-cleanup for DirectXTex to enable use of PCH through 'directxtexp.h' header
 177
 178 January 24, 2011
 179     Some code-cleanup for DirectXTex
 180     Added DXGI 1.2 implementation for DDSTextureLoader and DirectXTex guarded with DXGI_1_2_FORMATS compiliation define
 181
 182 December 16, 2011
 183     Fixed x64 compilation warnings in DDSTextureLoader
 184
 185 November 30, 2011
 186     Fixed some of the constants used in IsSupportedTexture(),
 187     added ability to strip off top levels of mips in DDSTextureLoader,
 188     changed DirectXTex to use CoCreateInstance rather than LoadLibrary to obtain the WIC factory,
 189     a few minor /analyze related annotations for DirectXTex
 190
 191 October 27, 2011
 192     Original release