src/external/3rd/application/DXTex/readme.txt

   1 //-------------------------------------------------------------------------
   2 //
   3 // Sample Name: DxTex
   4 //
   5 // Copyright (c) Microsoft Corporation. All rights reserved.
   6 //
   7 //-------------------------------------------------------------------------
   8
   9
  10 Description
  11 ===========
  12 The purpose of this tool is to allow DXSDK users to easily create texture
  13 maps that use the new DXTn compression formats.  Creating a DXTn-compressed
  14 texture is actually not that difficult to do: DirectDraw's Blt function can
  15 do the conversion for you.  Advanced developers will probably want to write
  16 their own tools that meet their specific needs.  But this tool provides useful
  17 basic functionality.
  18
  19
  20 DxTex Functionality
  21 ===================
  22 Opens BMP and DDS files (See below for a description of the DDS file format)
  23 Opens BMP files as alpha channel, either explicitly or implicitly (via
  24 foo_a.bmp naming)
  25 Saves textures in DDS format
  26 Supports conversion to all five DXTn compression formats
  27 Supports generation of mip maps (using a box filter)
  28 Supports visualization of alpha channel as a greyscale image or via a user-
  29 selectable background color
  30 Supports easy visual comparison of image quality between formats
  31
  32 Note: DxTex does not currently support textures with surface formats that
  33 do not contain at least an R, G, and B texture (such as D3DFMT_G16R16 and
  34 D3DFMT_A8), although D3DX can load and save such textures in DDS format.
  35
  36
  37 User Interface
  38 ==============
  39 DxTex uses a pretty traditional user interface.  Each texture map is a
  40 document, and several documents can be open at a time.  The one thing that
  41 is a bit unusual about the UI is that each document can hold the texture
  42 in either one or two formats at once while the document is open in DxTex.
  43 For instance, one could import a BMP file, which would automatically create
  44 a 32-bit ARGB texture.  One could then choose to convert the texture to
  45 DXT1 format.  The document now remembers the image in *both* formats, and
  46 the user can flip between the formats by clicking in the window or by
  47 choosing "Original" and "New" in the View menu.  This makes it easy for
  48 the user to observe any artifacts introduced by image compression, and to
  49 try several different compression formats without progressive degradation
  50 of the image  For instance, if this technique were not used and the user
  51 converted an image from ARGB to DXT1, all but one bit of alpha would be lost.
  52 If the user then decided to convert to DXT2, there would still be only two
  53 alpha levels.  With DxTex's system, the second conversion is done from the
  54 original ARGB format, and the DXT2 image will contain all 16 levels of alpha
  55 supported by DXT2.  When the image is saved, the "original" format is
  56 discarded, and only the "new" format is stored.
  57
  58 There are a few consequences of this system that one must remember:
  59 - If no format conversion has been requested since the document was opened,
  60   the one format is the "original" format and that is the format in which
  61   the image will be written when the document is saved.
  62 - If format conversion has been requested since the document was opened, the
  63   converted format is the "new" format and that is the format in which the
  64   image will be written when the document is saved.
  65 - If a second format conversion is requested, the "new" format from the first
  66   conversion is replaced with the second format.  The "original" format will
  67   be unchanged.
  68 - Generating of mip maps applies to both formats simultaneously.
  69 - If the original format has multiple mip maps, and conversion to a new format
  70   is requested, the new format will automatically have multiple mip maps as
  71   well.
  72 It's not as complicated as it sounds: with time, this two-format system
  73 becomes natural and efficient to use.
  74
  75
  76 DxTex Performance
  77 =================
  78 DxTex uses the Direct3D Reference Rasterizer to draw the textures,
  79 regardless of what 3D hardware is available.  So with larger textures
  80 (greater than 256x256), the program may be somewhat slow, depending on your
  81 CPU speed.
  82
  83
  84 DDS File Format
  85 ===============
  86 DxTex's native file format is called "DDS" file format, because it
  87 encapsulates the information in a DirectDrawSurface.  It has the following
  88 format:
  89
  90     DWORD dwMagic (0x20534444, or "DDS ")
  91     DDSURFACEDESC2 ddsd (this provides information about the surface format)
  92     BYTE bData1[] (this is the surface data for the main surface)
  93     [BYTE bData2[]...] (surface data for attached surfaces, if any, follow)
  94
  95 This format is easy to read and write, and supports features such as alpha
  96 and multiple mip levels, as well as DXTn compression.
  97
  98 The user should note that it is not necessary to use the DDS format in order
  99 to use DXTn-compressed textures, or vice-versa.  But the two work well
 100 together.
 101
 102
 103 Mip Maps
 104 ========
 105 Mip mapping is a technique that improves image quality and reduces texture
 106 memory bandwidth by providing prefiltered versions of the texture image at
 107 multiple resolutions.
 108
 109 To generate mip maps in DxTex, the width and height of the source image must
 110 both be powers of 2.  Choose "Generate Mip Maps" from the Format menu.
 111 Filtering is done via a simple box filter, i.e., the four nearest pixels are
 112 averaged to produce each destination pixel.  More sophisticated filtering can
 113 be found in other image processing programs.
 114
 115
 116 Alpha
 117 =====
 118 Many texture formats include an alpha channel, which provides opacity
 119 information at each pixel.  DxTex fully supports alpha in textures.  When
 120 importing a BMP file, if a file exists of the same size with "_a" at the end
 121 (e.g., foo.bmp and foo_a.bmp), the second file will be loaded as an alpha
 122 channel.  The blue channel of the second BMP is stored in the alpha channel.
 123 Once a document is open, the user can explicitly load a BMP file as the alpha
 124 channel via the "Open As Alpha Channel" command on the File menu.
 125
 126 To view the alpha channel directly without the RGB channels, choose "Alpha
 127 Channel Only" from the View menu.  The alpha channel will appear as a
 128 greyscale image.  Note that if no alpha channel has been loaded, the alpha
 129 channel will be 100% everywhere and the image will appear solid white when
 130 viewing "Alpha Channel Only".  To turn off "Alpha Channel Only", just choose
 131 that menu item a second time.
 132
 133 In the usual view, the effect of the alpha channel is visible because the
 134 window has a solid background color which shows through the texture where the
 135 alpha channel is less than 100%.  The user can change this background color
 136 by choosing "Change Background Color" from the View menu.  This choice does
 137 not affect the texture itself or the data that is written when the file is
 138 saved.
 139
 140 The DXT2 and DXT4 formats use premultiplied alpha, which means that the
 141 red, green, and blue values stored in the surface are already multiplied
 142 by the corresponding alpha value.  DirectDraw cannot blit from a surface
 143 containing premultiplied alpha to one containing non-premultiplied alpha,
 144 so some DxTex operations (Open as Alpha Channel, conversion to DXT3, and
 145 conversion to DXT5) are not possible on DXT2 and DXT4 formats.  Supporting
 146 textures using these formats is difficult on Direct3D devices which do
 147 not support DXTn textures, because DirectDraw cannot handle blitting them
 148 to a traditional ARGB surface either (unless that ARGB surface uses
 149 premultiplied alpha as well, which is rare).  So you may find it easier to
 150 use DXT3 rather than DXT2 and DXT5 rather than DXT4 when possible.
 151
 152
 153 Command-Line Options
 154 ====================
 155 Command-line options can be used to pass input files, an output file name, and
 156 processing options to DxTex.  If an output file name is specified, the program
 157 exits automatically after writing the output file, and no user interface is
 158 presented.
 159
 160 dxtex [infilename] [-a alphaname] [-m] [DXT1|DXT2|DXT3|DXT4|DXT5] [outfilename]
 161
 162 infilename:               The name of the file to load.  This can be a BMP or
 163                           DDS file.
 164
 165 -a alphaname:             If "-a" is specified, the next parameter is the name
 166                           of a BMP file to load as the alpha channel.  Note:
 167                           if no alpha filename is specified, DxTex will still
 168                           look for a file named infilename_a.bmp and, if it
 169                           exists, use that as the alpha channel.
 170
 171 -m:                       If this option is specified, mipmaps are generated.
 172
 173 DXT1|DXT2|DXT3|DXT4|DXT5: Specifies compression format.  If no format is
 174                           specified, the image will be in ARGB-8888.
 175
 176 outfilename:              Specifies the name of the destination file.  If this
 177                           is not specified, the user interface will show the
 178                           current file and all requested operations.  If an
 179                           outfilename is specified, the app will exit after
 180                           saving the processed file without presenting a user
 181                           interface.