Vtex (Source 1)

From Valve Developer Community
Jump to: navigation, search
English (en)
Edit
Not to be confused with VTEX (Source 2).

Vtex Vtex, or Valve Texture Tool, is the command-line tool used to convert targa (.tga), portable floatmap (.pfm), or Photoshop (.psd) (Orange box SDK) image files into Valve Texture Files (.vtf) for use in the Source Source engine.

Warning.pngWarning:It is recommended that you use the third-party tool VTFEdit instead. VTFEdit boasts a user-friendly interface,[Clarify] a wider array of accepted formats,[Clarify] the ability to change most VTF's properties without recompiling,[Clarify] a standalone viewer,[Clarify] and direct GCF access[Clarify].

Limitations

Stub

This article or section is a stub. You can help by adding to it.

  • Vtex takes significantly a longer time to process a 4096x4096 input than a 2048x2048 or smaller input. Older versions of Vtex don't support such high resolution textures at all.

Supported input formats

  1. Truevision Targa (.tga)
  2. Portable Floatmap (.pfm)
  3. Photoshop (.psd) image files (in all games since Source 2009)

Supported output formats

  1. Valve Texture Files (.vtf) for use in the Source Source engine

Usage

Basic

  1. Make sure that Steam is running.
  2. Place the targa image to be converted inside the SteamApps/common/gamefolder/materialsrc/ folder, where gamefolder is the game folder of the current game (cstrike/dod/hl2/hl2mp/tf). You can also place the image within a subfolder of this folder, to make Vtex compile the texture to the corresponding materials/ subfolder. (For instance, placing the image in a materialsrc/metal/ subfolder, will make Vtex compile the texture to the materials/metal/ subfolder.)
  3. If necessary, write a text (.txt) file containing a set of Vtex compile parameters. Give it the same name as the targa image (with the exception of the .txt extension) and put it in the same folder. If you choose to omit this list, Vtex will create an empty one for you during compilation.
  4. The Vtex executable (Vtex.exe) is located in the /Steam/SteamApps/common/gamefolder/bin/ folder, again where gamefolder is the folder that corresponds with the target game. It can be executed in one of two ways: Through the easy "drag-and-drop" method (described below), or the more advanced command prompt method, described here. Steam must run while it is executed.
  5. The resulting Valve Texture File (VTF) will be compiled to the materials/ folder of the current game by default. For instance, if the current game would be Half-Life 2, the texture file would be compiled to the SteamApps/common/Half-Life 2/hl2/materials/ folder. If the targa image resided within a subfolder, Vtex will compile the texture file to the corresponding materials/ subfolder. If that subfolder doesn't exist, Vtex will create it automatically.

The Drag-and-Drop Method

The drag-and-drop method is the easy way to use Vtex. Just drag the icon of either the targa image to be converted, or its list of compile parameters (from its materialsrc/ folder) on top of the icon of the Vtex executable (Vtex.exe) and let go, and Vtex will compile the texture file automatically.

Command-line interface

Main article:  Vtex CLI use

Compile parameters

Vtex can accept a list of additional compile parameters during its execution. These parameters are optional, but sometimes necessary to get a good result.[Clarify]

The list is written in the form of a simple text (.txt) document with the same name as the targa (.tga) image to compile, and it should be put in the same folder as it, namely in the SteamApps/common/gamefolder/materialsrc/ folder, where gamefolder is the game folder of the current game (cstrike/dod/hl2/hl2mp).

Example usage from one of the files for the console background:

nonice 1
nolod 1
nomip 1


Parameters

allmips
Force texture to use all mipmaps (No minimum mipmap).
alphatest_hifreq_threshhold
alphatest_threshhold
alphatest
Todo: What do these do?
alphatodistance
Creates alpha-to-distance textures.
anisotropic
Force at least Anisotropic filtering on the compiled texture.
bumpscale
Sets texture's bumpscale value, which controls normal map intensity.
clamps
clampt
clampu
Do not allow the texture to wrap in the S, T, or U coordinate space, respectively. This is most often used for sprites that are not tiled.
Tip.pngTip: When a texel is requested that is outside of the texture, one of two techniques is used: Clamping limits the texel to the texture size, moving it to the nearest if it is more than the texture size. Wrapping makes the texel move back into the texture by increments (each to size of the texture). Wrapping causes a texture to be repeated; clamping causes it to be in one spot only.
distancespread
How much to spread alpha when creating alpha-to-distance textures.
dudv
Texture is a Du/Dv map.
dxt5
Force DXT5 compression, even if the source has no alpha channel.
maxheight
maxheight_360
maxwidth
maxwidth_360
Sets maximum texture size for "High" (mat_picmip 0) texture quality. Negative mat_picmip settings will go above this limit.
mipblend
Todo: Figure out how to make this work
nocompress
Do not use compression on this texture. Useful for textures with fine gradation (like light halos).
nodebug
No debug override.
nolod
Do not use lower resolution versions of this texture regardless of texture quality (mat_picmip) settings. Used for non-world graphics such as HUD art.
nomip
Do not use mipmapping for this texture. Used for materials like skyboxes and menu backgrounds.
Bug.pngBug:The MIPs are still generated and loaded! Use VTFEdit to reduce texture footprint.
nonice
Do not use NICE filtering on this texture’s lower mip-levels.
normal
Texture is a normal map. Implies nonice, so all normals will be kept normalized during mipmap generation.
Note.pngNote: Automatically applies when the texture name ends with _normal
normalalphatodudvluminance
Use alpha channel as luminance when converting from normal maps to Du/Dv maps
normaltodudv
Converts the texture to a Du/Dv map.
numchannels
How many channels to import from source file. (1 = Red only, 2 = Red and Green, 3 = RGB, 4 = RGB + Alpha) Omitted color channels are replaced with full color intensity.
oneovermiplevelinalpha
Alpha channel fades out as mipmaps get smaller.
pfm
Source texture is a portable floatmap. Used for HDR.
pfmscale (float)
Used to scale floatmap intensity.
pointsample
Do not filter this texture in-game.
premultcolorbyoneovermiplevel
Color channel fades out as mipmaps get smaller. Used when converting normal maps to Du/Dv maps.
procedural
Texture is procedural.
reduce
reducex
reducey
Downscales on both, only X, or only Y axes, respectively. Value must be a power of two, and tells VTEX how to reduce the dimensions (2 = half size, 4 = quarter size, 8 = eighth size, etc.).
rendertarget
Texture is a rendertarget.
singlecopy
Todo: What does this do??
skybox
Used for compiling skyboxes. This assures the edges match between each facet.
spheremap_negz
spheremap_z
spheremap_negy
spheremap_y
spheremap_negx
spheremap_x
Todo: Are these functional?
ssbump
Used for self-shadowing bump maps.
Note.pngNote: Automatically applies when the texture name ends with _height-ssbump
startframe (integer)
endframe (integer)
Used for animated textures. Textures must be named as texture000, texture001, texture002, etc. The startframe defines the beginning frame and the endframe defines the ending frame. Up to 1,000 frames are allowed.
stripalphachannel
Used to tell Vtex to ignore the source texture's alpha channel.
stripcolorchannel
Used to create a texture with no color data.
trilinear
Force at least Trilinear filtering on the compiled texture.
volumetexture
Creates a volumetric texture.

using .psd 'file info' parameters

Textures compiled from .psd files can have command line parameters saved into the .psd directly. To do this, use the 'File Info' menu in Photoshop and add your Vtex commands into the "description" text field. These parameters will get evaluated by Vtex when the .psd file is compiled.

Here's an example of usage for creating a flashlight that won't tile:

clamps 1;
clampt 1;
border 0;


Troubleshooting

Local Steam Service is not running

Vtex will give the following error:

SteamStartup() failed: SteamStartup(0xf,0x0012F0E4) failed with error 108: The local Steam Service is not running

Steam must run while Vtex is run. Start Steam to fix this.

Problem figuring out outputdir

Vtex will give the following error:

Problem figuring out outputdir for <path>

As a first step, check that the texture to convert is really in the \sourcesdk_content\gamedir\materialsrc folder, where gamedir is the game folder (cstrike/dod/hl2/hl2mp).

If the texture is in the correct folder, the error might instead be caused by a complication with the environment variables. Primarily, this should be able to be eliminated by using VConfig and ensuring the selected mod has been run at least once. However, there are cases where this doesn't solve the problem.

One solution is to remove the instance of the VProject Environment variable. In Windows XP this can be accomplished by the following:

  1. Right-click on My computer and click on Properties.
  2. Select the Advanced tab.
  3. Click on Environment Variables near the bottom of the window.
  4. In the System variables section scroll down and highlight the line VProject.
  5. Click the Delete button.
  6. Click OK twice to exit.

However, this solution will create the Unable to find gameinfo.txt error instead.

Todo: Delete this non-functioning solution alternative?

Alternative solution

vtex.exe cannot understand spaces in the input file. One solution is to create a folder directly on the C:/ drive with the same name as the original one the vtex shortcut was pointing at. For example, create C:/tf instead of C:\Program Files\Steam\steamapps\<account_name>\team fortress 2\tf. Update the vtex.exe shortcut to point to this new folder. In this folder, put the gameinfo.txt from the original folder, as well as an empty materialsrc and materials folder. Place your file to be converted in the new materialsrc folder. Now drag-and-drop the file onto the vtex shortcut, and the output will be in the new materials folder.

"Unable to find gameinfo.txt"

Vtex will give the following error and instructions:

Unable to find gameinfo.txt. Solutions:

1. Read http://www.valve-erc.com/srcsdk/faq.html#NoGameDir
2. Run vconfig to specify which game you're working on.
3. Add -game <path> on the command line where <path> is the directory that gameinfo.txt is in.

This error will occur after VProject has been removed using the steps above.

Open Source SDK and change the Current Game.

Note.pngNote: The link at step 1 won't provide a solution. (The page is really old.)

Setup file gameinfo.txt doesn't exist

The Nov 7th, 2007 SDK release includes Orange Box with TF2 and trying to use vtex in this new SDK update to create a vtf file for Team Fortress 2 results in the following error message:

"Setup file 'gameinfo.txt' doesn't exist in subdirectory 'C:\Program Files\Steam\steamapps\player name\sourcesdk\bin\orangebox\bin\vconfig'. check your -game parameter or VCONFIG setting.".

Assuming that this is the same error as "Unable to find gameinfo.txt" above, then trying to run vconfig.exe results in this error:

"This application has failed to start because Steam.dll was not found. Re-installing the application may fix this problem."

Solution:

  1. Create a shortcut to vtex.exe which is located in "C:\Program Files\Steam\steamapps\player_name\sourcesdk\bin\orangebox\bin\vtex.exe" and select Properties.
  2. At the end of the Target text add -game "C:\Program Files\Steam\steamapps\player_name\team fortress 2\tf" -nop4

Valve intends to fix the problem with requirement of a -nop4 argument to be added to the target.

TGA is bogus

Vtex will give the following error:

TGA <path> is bogus!

The texture image you are trying to convert is not recognized as a valid targa (.tga) file. Make sure that it is, and that it is either 24 bit/pixel or 32 bit/pixel. (16 bit/pixel is not recognized.)

"Warning: falling back to auto detection of vconfig" (Windows Vista)

Vtex will give the following error:

Todo: Please provide an exact quote of the error.

Make a shortcut for vtex.exe and add -game [path to game directory]

Example: -game c:/steam/steamapps/sourcemods/Awakening

If there are spaces in any of the folders in your path use "

Example: -game "c:/program files/steam/steamapps/sourcemods/insurgency"

Error loading texture texturename.pfm

The byteorder ( endian ) of your .pfm is probably not the correct one.
If you exported your texture from photoshop, this might happen depending on the specific photoshop version you are using.
A workaround for this issue is by converting to .pfm using Imagemagick ( Make sure to download the version specific to your OS that has HDR imaging enabled! )
Run your texture ( .tif, .hdr, .exr ... ) through the tool with -endian LSB and the resulting .pfm should no longer make vtex complain!

See Also

Icon-visibility-filled.pngIcon-chat.pngIcon-edit-filled.png Official Source SDK tools
Map editors Hammer Hammer
Map compilers vbspvvis • vrad • vmpi
Map tools bspzip • glview • VBSP2 • vbspinfo
Model compilers Studiomdl
Model tools Dmxconvert • Dmxedit • HLFaceposer HLFaceposer • HLMV HLMV • Itemtest • Modelbrowser • QC_Eyes
Texture tools Height2Normal Height2Normal • height2ssbump • makevmt • mksheet • Pfm2tgas • Shadercompile • Splitskybox • Vtex Vtex • VTF2TGA VTF2TGA • xwad
Sound tools VSoundEdit
Engine tools ActBusy Script Editor • Commentary Editor • Foundry • Material Editor • Particle Editor • Source Filmmaker Source Filmmaker
Other Captioncompiler • Demoinfo • Elementviewer • Motionmapper • Sfmgen • VConfig • Vfont • Vfont_decompiler • VICE • vpk