View source for VTEX (Valve Texture Tool)

{{LanguageBar}}
{{for|the Source 2 file format|[[VTEX (Valve Texture)]]}}

{{vtex|4}}, or Valve Texture Tool, is the [[command-line]] tool used to convert [[TGA|targa (.tga)]], [[PFM|portable floatmap (.pfm)]], or [[PSD|Photoshop (.psd)]] (Orange box SDK) image files into [[VTF|Valve Texture Files (.vtf)]] for use in the {{src|4}} engine.

{{warning|It is '''recommended''' that you use a third-party tool such as {{vtfeditreloaded|3.1}} instead, unless if you are attempting to import/export [[HDR]] textures, which VTFEdit has limited support for. VTFEdit boasts a user-friendly GUI interface, a wider array of accepted input formats, more control over the [[VTF#Image data formats|image format]], the ability to change most properties of a VTF without recompiling, and a standalone viewer.}}

== Limitations ==
{{stub|section=1}}
{{warning|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.
{{tip|{{tf2|2}}: A patched Vtex that supports 4096x4096 TGA textures can be [https://web.archive.org/web/20240222001028id_/https://cdn.discordapp.com/attachments/596042830259027990/1136772785021140992/vtex_dll.dll downloaded here].}} }}
{{bug|{{tf2}} Vtex generates noticeably lower-quality results for DXT-compressed formats than the Vtex included in most other games, such as {{asw}}, {{CSGO}}, or {{hl2}}{{cn}}.}}
{{note|Vtex is only capable of creating a limited subset of VTF's supported [[VTF_(Valve_Texture_Format)#Image_data_formats|image formats]], namely DXT1, DXT5, BGR888, BGRA8888, RGBA16161616f, A8, UV88, and UVLX8888.}}

== Supported input formats ==
# [[TGA|Truevision Targa (.tga)]]
# [[PFM|Portable Floatmap (.pfm)]]
# [[PSD|Photoshop (.psd)]] image files {{src09|since}}

== Supported output formats ==
# [[VTF|Valve Texture Files (.vtf)]] for use in the {{src|4}} engine

== Usage ==
=== Basic ===
#Make sure that [[Steam]] is running.
#Place the targa image to be converted inside the <code>SteamApps/common/gamefolder/materialsrc/</code> folder, where ''gamefolder'' is the game folder of the current game (<code>cstrike</code>/<code>dod</code>/<code>hl2</code>/<code>hl2mp</code>/<code>tf</code>). You can also place the image within a subfolder of this folder, to make Vtex compile the texture to the corresponding <code>materials/</code> subfolder. (For instance, placing the image in a <code>materialsrc/metal/</code> subfolder, will make Vtex compile the texture to the <code>materials/metal/</code> subfolder.)
#If necessary, write a [[txt|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.
#The Vtex executable (<code>Vtex.exe</code>) is located in the <code>/Steam/SteamApps/common/gamefolder/bin/</code> folder, again where <code>gamefolder</code> 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 [[Vtex CLI use|here]]. Steam must run while it is executed.
::{{note|The {{src13}} versions of vtex do not seem to require Steam to be running.}}
#The resulting Valve Texture File (VTF) will be compiled to the <code>materials/</code> 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 <code>SteamApps/common/Half-Life 2/hl2/materials/</code> folder. If the targa image resided within a subfolder, Vtex will compile the texture file to the corresponding <code>materials/</code> 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 <code>materialsrc/</code> 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|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 [[TGA|targa (.tga)]] image to compile, and it should be put in the same folder as it, namely in the <code>SteamApps/common/gamefolder/materialsrc/</code> folder, where ''gamefolder'' is the game folder of the current game (<code>cstrike</code>/<code>dod</code>/<code>hl2</code>/<code>hl2mp</code>).

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

<pre>
// This is a comment, and will be ignored
nonice 1
nolod 1
nomip 1
</pre>


=== Parameters ===
; {{mono|allmips}}
: Force texture to use all mipmaps (no minimum mipmap).
; {{mono|alphatest}}
: Keep alpha channels of mipmaps binary (only transparent or opaque), for use with {{cmd|$alphatest}}.
: No effect on the full resolution texture (mipmap 0).
{{modernImportant|Should not be used with  {{cmd|$allowalphatocoverage}} textures.}}
; {{mono|alphatest_hifreq_threshhold}}
; {{mono|alphatest_threshhold}}
: Fine-grain control for alphatest mipmap generation{{elaborate}}
; {{mono|alphatodistance}}
: Creates [[$distancealpha|alpha-to-distance]] textures.
; {{mono|anisotropic}}
: Use anisotropic filtering on the compiled texture, even if the user has selected bilinear or trilinear filtering in their video settings.
; {{mono|bumpscale}}
: Sets texture's bumpscale value, which controls normal map intensity.
; {{mono|clamps}}
; {{mono|clampt}}
; {{mono|clampu}}
: Do not allow the texture to wrap in the S (sides), T (top), or U ({{clarify}} coordinate space, respectively. This is most often used for sprites that are not tiled. {{tip|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.}}
; {{mono|distancespread}}
: How much to spread alpha when creating alpha-to-distance textures.
; {{mono|dudv}}
: Texture is a Du/Dv map.
; {{mono|dxt5}}
: Force [[DirectX Texture compression 5|DXT5]] compression, even if the source has no alpha channel.
; {{mono|invertgreen}} {{since|{{csgobranch}}}}{{confirm}}
: Invert the green channel of the input texture (used for converting [[OpenGL]] normal maps to [[DirectX]]).
; {{mono|manualmip}} {{since|{{csgobranch}}}}
: Use pre-authored mipmaps instead of generating them from the full resolution texture
: {{note | You will need to create each mip level for your final VTF. Use the naming convention: "<texture_name>_mipX.tga", where "X" represents the mip level you are creating. Each mip level should be exactly half the size of the previous one. For example, if you start with a 128x128 image named `<texture_name>.tga`, your first mip level `<texture_name>_mip0.tga` should also be 128x128. Continue to halve the image dimensions for each subsequent mip level until you reach `<texture_name>_mip7.tga`, which will be a 1x1 image.}}
{{warning|Not compatible with {{mono|normal}}, {{mono|nomip}}, {{mono|volumetexture}}, or {{mono|specvar}}}}
; {{mono|maxheight}}
; {{mono|maxheight_360}}
; {{mono|maxwidth}}
; {{mono|maxwidth_360}}
: Sets maximum texture resolution for "High" ({{cmd|mat_picmip|0}}) texture quality.
: If absent, both "High" ({{cmd|mat_picmip|0}}) and "Very High" ({{cmd|mat_picmip|-1}}) texture quality will use the full-resolution texture.
: {{modernImportant|This should not be set to anything lower than half the resolution of the full-size texture, or else it will require the user to manually set a {{cmd|mat_picmip}} value lower than {{mono|-1}} ("Very High" texture quality in video settings), which requires {{cmd|sv_cheats}} in games other than {{tf2|2}}.<br>For example, a 2048x2048 texture could have these values set to {{mono|1024}}, but shouldn't set them to {{mono|512}}.}}
; {{mono|mipblend}} {{since|{{src07}}}}
: Fade out to a specific color or alpha starting with mip level 3. Takes one of the following options:
:* {{mono|detail}} - Fade out all color channels to 128, for detail textures using {{cmd|$detailblendmode|0}}.
:* {{mono|1=skip=}} - ???
:* {{mono|1=r=#}}, {{mono|1=g=#}}, {{mono|1=b=#}}, {{mono|1=a=#}} - Fade out to the specified value. Include a {{mono|mipblend}} statements for each channel, like so
  "mipblend" "r=247"
  "mipblend" "g=154"
  "mipblend" "b=16"
  "mipblend" "a=255"
:: Any omitted values will be treated as zero.
::{{bug|Only works correctly when used in conjunction with {{mono|allmips}}.}}

; {{mono|nocompress}} {{since|{{src07}}}}
: Do not use compression on this texture. Useful for textures with fine gradation (like light halos).
; {{mono|nodebug}}
: No debug override.
; {{mono|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.
; {{mono|nomip}}
: Do not use mipmapping for this texture. Used for materials like skyboxes and menu backgrounds. {{bug|The MIPs are still generated and loaded{{cn|they are generated, but are they really loaded?}}! Use [[VTFEdit]] to create VTFs without mipmaps, but note that such textures will not display properly in {{hammer|4.1|addtext='s}} texture browser (fixed in {{hammer++|4.1}} build 8866).}} {{Question|The aforementioned solution won't work for uncompressed [[HDR]] textures as VTFEdit can only ''open'' HDR [[VTF]]s and convert them to other image formats (it can't create them from [[PFM]]s as VTEX does). This is an issue; uncompressed HDR textures add up quickly in file size. A 512x512px RGBA16161616f VTF with mips is around {{mono|2.66 MB}}. Are there any known methods for stripping these HDR VTFs of their mips when unneeded to reduce the size of VTFs as much as possible?}}
; {{mono|nonice}}
: Do not use [[NICE filtering]] on this texture’s lower mip-levels.
; {{mono|normal}}
: Texture is a normal map. Implies {{mono|nonice}}, so that all normals will be kept normalized during mipmap generation. Also regenerates the Blue color channel if missing, at least in some versions{{which}}.
:{{note|Automatically applies when the texture name ends with <code>_normal</code>}}
; {{mono|normalalphatodudvluminance}}
: Use alpha channel as luminance when converting from normal maps to Du/Dv maps
; {{mono|normaltodudv}}
: Converts the texture to a Du/Dv map.
; {{mono|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; cannot be used to create an I8-encoded VTF.
; {{mono|oneovermiplevelinalpha}}
: Alpha channel fades out as mipmaps get smaller.
; {{mono|pfm}}
: Source texture is a portable floatmap. Used for HDR.
; {{mono|pfmscale "<float>"}}
: Used to scale floatmap intensity.
; {{mono|pointsample}}
: Do not filter this texture in-game.
: {{bug|Affects both the magnification and minimization filters instead of only the magnification filter, breaking mipmapping. Combine with {{mono|nomip}} to avoid wasting VRAM. {{tip|Prefer using {{cmd|$pointsamplemagfilter}} if available.}} }}
; {{mono|premultcolorbyoneovermiplevel}}
: Color channel fades out as mipmaps get smaller. Used when converting normal maps to Du/Dv maps.
; {{mono|procedural}}
: Texture is procedural.
; {{mono|reduce}}
; {{mono|reducex}}
; {{mono|reducey}}
: Downscales on both axes, only X axis, or only Y axis, 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.).
; {{mono|rendertarget}}
: Texture is a rendertarget.{{clarify}}
; {{mono|singlecopy}}
: {{todo|What does this do??}}
; {{mono|skybox}}
: Used for compiling [[skybox]]es. This assures the edges match between each facet.
; {{mono|specvar}}
: Like mipblend, but for [[$envmapmask|specular masks]].{{why}}
: Implies {{mono|allmips}}.
; {{mono|spheremap_negz}}
; {{mono|spheremap_z}}
; {{mono|spheremap_negy}}
; {{mono|spheremap_y}}
; {{mono|spheremap_negx}}
; {{mono|spheremap_x}}
: {{modernConfirm|Are these functional?}}
; {{mono|ssbump}}
: Used for [[$ssbump|self-shadowing bump maps]].
{{note|Automatically applies when the texture name ends with <code>_height-ssbump</code>}}
; {{mono|startframe <integer>}}
; {{mono|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.
{{note|The 1000-frame limit is a {{vtex|4.1}} limit, not an engine limit. [[VTFLib]] can add an effectively unlimited number of frames (as long as the resulting VTF fits in the 32MB size limit on SDK2013-based games).}}
; {{mono|stripalphachannel}}
: Used to tell Vtex to ignore the source texture's alpha channel.
: If the texture is SDR, the resulting VTF will be encoded as DXT1 or BGR888 instead of DXT5 or BGRA8888, respectively (depending upon presence of {{mono|nocompress}}), unless the {{mono|DXT5}} parameter is used.
: If the texture is HDR, the resulting alpha channel will be completely opaque ("white").
; {{mono|stripcolorchannel}}
: Used to create a texture with no color data. 
: Implies {{mono|nocompress}}; the resulting VTF will be encoded as A8. Not compatible with {{mono|pfm}}.
; {{mono|trilinear}}
: Use at least trilinear filtering on the compiled texture, even if the user has selected bilinear filtering in their video settings.
; {{mono|volumetexture}}
: Creates a volumetric texture.
: Implies {{mono|nocompress}} and {{mono|nonice}}.

=== 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:

<pre>
clamps 1;
clampt 1;
border 0;
</pre>

== 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 <code>\sourcesdk_content\gamedir\materialsrc</code> folder, where ''gamedir'' is the game folder (<code>cstrike</code>/<code>dod</code>/<code>hl2</code>/<code>hl2mp</code>).

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:

#Right-click on ''My computer'' and click on ''Properties''.
#Select the ''Advanced'' tab.
#Click on ''Environment Variables'' near the bottom of the window.
#In the ''System variables'' section scroll down and highlight the line ''VProject''.
#Click the ''Delete'' button.
#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 <code>gameinfo.txt</code> is in.

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

Open Source SDK and change the ''Current Game''.

{{note|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 <code>vconfig.exe</code> 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: 
#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.
#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 <code>-nop4</code> 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. (8 or 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.<br>
If you exported your texture from photoshop, this might happen depending on the specific photoshop version you are using.<br>
A workaround for this issue is by converting to .pfm using [https://imagemagick.org/ Imagemagick] ( Make sure to download the version specific to your OS that has HDR imaging enabled! )<br>
Run your texture ( .tif, .hdr, .exr ... ) through the tool with <code>-endian LSB</code> and the resulting .pfm should no longer make vtex complain!

== See also ==
* [[Creating a Material]]

{{SDKTools}}

[[Category: Material System]]