DirectX Ops Script Commands

The DirectX Ops tool (see DirectX Ops (dxops.exe)) can accept an expression string, which contains a series of script commands, files and optional arguments. Each expression is built from one or more of the following script commands:

I/O Script Commands Description
load Load a model or texture file
save Save model or texture to file
unload Remove textures or models from DXOps
Mesh Script Commands Description
addvdata Add vertex elements to a mesh vertex stream
clean Clean mesh
clonevdata Adds vertex elements to the vertex streams
delvdata Deletes vertex elements to a mesh vertex stream
flatten Removes hierarchy from mesh
genadjacency Generates adjacency data for mesh
gennormals Generates normals for mesh
gentangentframes Generates tangent frames for mesh
meshes Print information about loaded meshes
optimize Optimize meshes
reset Resets DXOps
stripify Convert a mesh into triangle strips
uvatlas Creates UVAtlas for mesh
validate Validate mesh
Texture Script Commands Description
genmipmaps Generates mipmaps for texture(s)
newtex2d Creates a new texture
newtex3d Creates a new volume texture
newtexcube Creates a new cube texture
reformat Changes texture format
resize Resizes the texture
shade Applies a shader to a texture
slice2d Creates a new 2D texture from an existing texture surface
splice2d Inserts a surface into an existing texture
textures Print information about loaded textures

The script commands can be entered into the tool as command line arguments or from a script file. Each command has zero or more arguments passed in as name-value pairs, with the name and the value separated by a colon. All commands are either I/O or perform some operation on the loaded meshes. Almost every script command has corresponding API(s) in the DirectX SDK that do almost the exact same thing.

addvdata Script Command

Description:

Adds vertex elements to the vertex streams associated with the meshes.

Syntax:

addvdata src:string type:string usage:string usageIdx:int;

Where:

Example:

addvdata type:FLOAT3 usage:TANGENT usageIdx:0;

Remarks:

The new element is appended to the end of the vertex declaration and to the end of each vertex in the vertex buffer. Note that this command will not initialize any new data added to each vertex. For example, if adding normals a call to gennormals is needed to generate valid normal values for each vertex after they have been added to the declaration.

clean Script Command

Description:

Clean the mesh (or meshes).

Syntax:

clean src:string;

Where:

Example:

clean src:tiger;

Remarks:

Clean calls validation internally; if validation fails, the mesh cannot be cleaned.

Cleans the following issues with the mesh:

This script command uses D3DXCleanMesh.

clonevdata Script Command

Description:

Adds vertex elements to the vertex streams associated with the meshes.

Syntax:

clonevdata src:string usage:string usageIdx:int newUsage:string newUsageIdx:int;

Where:

Example:

clonevdata usage:TANGENT usageIdx:0 newUsage:TEXCOORD newUsageIdx:1;

Remarks:

The new element is appended to the end of the vertex as well as the vertex declaration.

delvdata Script Command

Description:

Removes vertex elements from the vertex streams associated with the meshes.

Syntax:

delvdata src:string usage:string usageIdx:int;

Where:

Example:

delvdata usage:TANGENT usageIdx:1;

Remarks:

This will remove the specified element from the declaration as well as from the vertices themselves.

flatten Script Command

Description:

Converts all of the meshes in a model into a single non-hierarchical mesh.

Syntax:

flatten dst:string src:string;

Where:

Example:

flatten dst:christmasTreeOneMesh src:christmasTreeWithSeparateOrnaments;

Remarks:

This will also remove any skin or animation information from the mesh.

This script command uses D3DXConcatenateMeshes.

genadjacency Script Command

Description:

Generates adjacency data for meshes, replacing existing data if it exists.

Syntax:

genadjacency src:string type:[topological|geometric] epsilon:float;

Where:

Example:

genadjacency type:topological;

Remarks:

This script command uses ID3DXBaseMesh::ConvertPointRepsToAdjacency for the topological method, and ID3DXBaseMesh::GenerateAdjacency for the geometric method.

genmipmaps Script Command

Description:

Generates mipmaps for the specified textures.

Syntax:

genmipmaps src:string start:int dither:int filter:string;

Where:

Example:

genmipmaps src:LobbyCube start:0 filter:Linear;

Remarks:

This script command uses D3DXFilterTexture.

gennormals Script Command

Description:

Computes vertex normals for every mesh.

Syntax:

gennormals src:string;

Where:

Example:

gennormals src:tiger;

Remarks:

If no normals are stored in the mesh before this command is called, then a call to the addvdata command must be made first, which will add normal data to the vertex declaration and assign empty values for the normals. Calling this command after adding normals to the vertex declaration will turn the normals into valid values.

This script command uses D3DXComputeNormals.

gentangentframes Script Command

Description:

Computes tangent frames for every mesh.

Syntax:

gentangentframes src:string texIdx:int ortho:string normalizePartials:[0|1] weight:string wrap:string threashPE:float threashSP:float threashNE:float;

Where:

Example:

gentangentframes texIdx:1 ortho:U weight:Area threshNE:0.5f;

Remarks:

This script command uses D3DXComputeTangentFrameEx.

load Script Command

Description:

Load a mesh or texture file.

Syntax:

load fileName:string srgb:int;

Where:

Example:

load fileName:tiger.x;

Remarks:

If the model file has a hierarchy, the hierarchy will be maintained when loading; if filename contains wildcards, all files matching the file specification are loaded; if filename is not an absolute path, the path is assumed to be relative to the current working directory.

This script command uses D3DXLoadMeshHierarchyFromX if loading a mesh, and D3DXCreateTextureFromFile if loading a texture.

meshes Script Command

Description:

Log information about all models and their meshes into the log file specified in the command line arguments.

Syntax:

meshes src:string;

Where:

Example:

meshes src:tiger;

newtex2d Script Command

Description:

Creates a new 2D texture.

Syntax:

newtex2d dst:string format:string width:int height:int numMips:int src:string;

Where:

Example:

newtex2d dst:newLobby format:A16B16G16R16 width:500 height:500;

Remarks:

This script command uses IDirect3DDevice9::CreateTexture.

newtex3d Script Command

Description:

Creates a new cube texture.

Syntax:

newtex3d dst:string format:string width:int height:int depth:int numMips:int src:string;

Where:

Example:

newtex3d dst:newLobby3D format:A16B16G16R16F width:500 height:500;

Remarks:

This script command uses IDirect3DDevice9::CreateVolumeTexture.

newtexcube Script Command

Description:

Creates a new cube texture.

Syntax:

newtexcube dst:string format:string size:int numMips:int srcXP:string srcXM:string srcYP:string srcYM:string srcZP:string srcZM:string;

Where:

Example:

newtexcube dst:newEnvironmentMap format:A16B16R16F size:512;

Remarks:

This script command uses IDirect3DDevice9::CreateCubeTexture.

optimize Script Command

Description:

Optimizes and welds vertices the meshes.

Syntax:

optimize src:string splits:int noCache:int weldAll:[none|epsilon|all] e:float P:float W:float N:float T:float B:float UV:float D:float S:float PS:float F:float;

Where:

Example:

optimize e:10e-9f;

Remarks:

This optimization allows the meshes to be more optimal for performance. The primary optimization that this command does is vertex welding, which optimizes the mesh by removing duplicate vertices.

This script command uses D3DXWeldVertices and ID3DXMesh::Optimize.

reformat Script Command

Description:

Changes the format of the specified textures.

Syntax:

reformat src:string format:string;

Where:

Example:

reformat format:A4R4G4B4;

Remarks:

This script command uses D3DXLoadSurfaceFromSurface.

reset Script Command

Description:

Resets as if DXOps has been restarted. Equivalent to calling unload on all objects.

Syntax:

reset;

resize Script Command

Description:

Resizes a texture.

Syntax:

resize src:string width:int height:int depth:int dither:int filter:string;

Where:

Example:

resize width:200 height:200;

Remarks:

This script command uses D3DXLoadSurfaceFromSurface.

save Script Command

Description:

Saves the models or textures to a file.

Syntax:

save src:string fileName:string xFileType:string;

Where:

Example:

save src:tiger fileName:tiger_modded.x xFileType:text;

Remarks:

This script command uses D3DXSaveMeshHierarchyToFile if saving a model.

shade Script Command

Description:

Calls a user-defined HLSL shader to modify a texture.

Syntax:

shade src:string shader:string fileName:string ...parameters...;

Where:

Passing Parameters Into Shaders

The shade script command allows you to initialize parameters in your HLSL shader. Doing so follows the basic syntax <name of parameter>:string. The string will be used initialize the specified parameter and the format of that string will depend on the data type of parameter that you are initializing.

For integers, floating point numbers, and matrices, the values are passed in as comma-delimited lists of numbers. For example:

float pi;
float3 viewVec;
matrix4x4 viewMat;

Would be initialized in the shade command by:

pi:'3.14' viewVec:'0,1,0' viewMat:'1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1'

Textures are passed into the shader by the name of their sampler. For example:

textureCUBE TableClothTex;
samplerCUBE TableClothSamp = sampler_state
{
    Texture = (TableClothTex);
    MinFilter = Linear;
    MagFilter = Linear;
};

Would be initialized in the shade command by:

TableClothSamp:'TabCloth'

Where TabCloth is a texture loaded into DXOps before the shade command was called. Below is an example usage of the shade script command that will create a texture that blends from white to black in the y direction.

If the HLSL file defines a sampler parameter with the name "Target", then the shade script command will automatically fill that parameter with the target texture. See the Using the Shade Script Command example.

HLSL Function Requirements

The function definitions for these HLSL texture shaders follow a syntax slightly different from vertex and pixel shaders. There can be three types of texture shader functions - one for 2D textures, one for 3D textures, and one for cube textures - each of which follows this convention:

For 2D textures:

float4 main(float2 UV : TEXCOORD0, float2 PixelSize : TEXCOORD1) : COLOR

Where UVs are 0 to 1

For 3D textures:

float4 main(float3 UVW : TEXCOORD0, float3 PixelSize : TEXCOORD1) : COLOR

Where UVWs are 0 to 1.

For cube textures:

float4 main(float3 UVW : TEXCOORD0, float3 PixelSize : TEXCOORD1) : COLOR

Where UVWs are -1 to 1.

PixelSize will have a zero on one of the axes. This will indicate which axis of the cube you are currently shading. Look to the sign of the corresponding axis in the UVW variable to determine if you are working on the positive or negative face along that axis. See the Using the Shade Script Command example.

Example:

newtex2d dst:'test' format:A8R8G8B8 width:64 height:64 mips:0; 
shade fileName:'ramp.psh' top:'1,1,1' bottom:'0,0,0'; 
save fileName:'t-ShadeTex2.dds';

Where ramp.psh is:

float3 top;
float3 bottom;

float4 main(float2 UV : TEXCOORD0, float2 PixelSize : TEXCOORD1) : COLOR
{
    return float4( lerp(bottom, top, UV.yyy ), 1);
}

This example will generate an image that looks like this:

Remarks:

This will not work on DXT compressed textures. If you have a DXT compress texture and wish to run the shade command on it, try reformatting the texture to a format that is valid as a render target and then reformatting it back to the desired format afterwards.

reformat 'A16B16G16R16F'; 
shade 'RedXGreenYPlusTarget-cube.psh'; 
reformat 'Dxt1';

This script command uses D3DXFillTextureTX.

slice2d Script Command

Description:

Creates a new 2D texture from an existing texture surface.

Syntax:

slice2d dst:string src:string volume:int face:string mipMap:int;

Where:

Example:

slice2d dst:bliss2 src:bliss;

Remarks:

This script command uses D3DXLoadSurfaceFromSurface.

splice2d Script Command

Description:

Inserts a surface into an existing texture.

Syntax:

splice2d dst:string src:string volume:int face:string mipMap:int;

Where:

Example:

splice2d dst:bliss src:azul;

Remarks:

This script command uses D3DXLoadSurfaceFromSurface.

stripify Script Command

Description:

Attempts to optimize meshes by ordering their triangles into strips.

Syntax:

stripify src:string splits:[0|1];

Where:

Example:

stripify src:tiger;

Remarks:

Does the following:

This script command uses ID3DXMesh::Optimize (with D3DXMESHOPT_STRIPREORDER).

textures Script Command

Description:

Log information about all meshes into the log file specified in the command line arguments.

Syntax:

textures src:string;

Where:

unload Script Command

Description:

Removes the specified texture(s) or model(s) from DXOps.

Syntax:

unload src:string type:string;

Where:

Example:

unload tiger type:models;

uvatlas Script Command

Description:

Partitions and packs a uvatlas for the meshes.

Syntax:

uvatlas src:string maxCharts:int stretch:float gutter:int width:int height:int;

Where:

Example:

uvatlas maxCharts:0 stretch:0.5 gutter:2.5 width:512 height:512;

Remarks:

This script command uses D3DXUVAtlasCreate.

validate Script Command

Description:

Validates meshes and sends warnings to the log if there are any.

Syntax:

validate src:string;

Where:

Example:

validate src:tiger;

Remarks:

Checks the following data:

This script command uses D3DXValidMesh.

See Also

DirectX Content Tools, DirectX Ops (dxops.exe)