Table Of Contents
The Texture Processor tool converts image files into a Redshift renderable format. Normally texture conversion is executed automatically in the background when rendering textures that have not yet been converted, but it can also be used off-line to batch convert textures so the automatic conversion can be skipped later. It is particularly useful to pre-convert textures off-line when you have a lot of them on a shared texture source folder over a network, because in some cases automatic texture conversion that occurs locally on the render machine can be slower than the actual rendering!
The Texture Processor converts textures so that the result is stored side-by-side with the source texture, having the same name and the extension replaced with ".rs***bin".
When pre-converting textures, the converted textured must remain side-by-side with the source texture or else it will not be found by Redshift. If Redshift does not find a converted texture with a source texture, the source texture will be automatically converted at render time.
By default, when Redshift finds a pre-converted texture at render time, it will copy it to the local texture cache folder and subsequently reference it from there. The assumption is that the local texture cache folder has better IO performance than the source texture folder, this is common for example when source textures are stored on slower network drives or when the local texture cache folder is on an SSD drive while the source texture folder is on a mechanical drive. In such cases, this is an important optimization as it ensures the best performance for out-of-core texture streaming.
In situations where the assumption of differences in IO performance between the local texture cache folder and the source texture folder does not hold, this optimization will actually hurt performance. For example, if the texture cache folder is on a slower network drive or if the texture cache folder and source texture folder are located on the same drive or drives of equal performance. In these cases, this can be disabled by turning OFF the Copy Pre-Converted Textures to Cache Folder option on the Sampling tab of the Redshift render options.
Texture naming is important when using the Texture Processor, all textures should have unique file names without taking into account their file extensions. If you have two textures, for example, one named "wall_displace.jpg" and another named "wall_displace.exr" there is no way for the texture processor to differentiate from each other — both textures will result in a pre-converted texture called "wall_displace.rstexbin" which could cause issues.
Using the Texture Processor is straight forward, first start by locating the "redshiftTextureProcessor" in the following default location:
The examples below use Windows but the same general command structure will work in all operating systems.
Then call the Redshift Texture Processor in a command line interface program. In Windows this can be easily done by typing "cmd" in the file path of an Explorer window which will open a command prompt from that location.
The syntax for the Redshift Texture Processor is simple:
redshiftTextureProcessor.exe inputfile [options]
In the inputfile section include the path to your texture followed by the [options] that are needed to properly convert the texture, for example, an OCIO color space. In the following example, a diffuse color texture would be pre-converted using the sRGB color space by specifying the path to the OCIO config and the color space. For more information on the available options, see the Command Line Options section on this page below.
redshiftTextureProcessor.exe C:\demo\texproc\textures\diffuse_color.jpg -ociopath C:\ProgramData\redshift\Data\OCIO -cs "sRGB"
The Texture Processor supports wildcards for its inputfile argument which can be extremely helpful for quickly converting textures that all need the same options and all have a similar file extension or file name. For example, to convert all .exr files in the directory you would use something like the following command.
redshiftTextureProcessor.exe C:\demo\texproc\textures\*.exr -ociopath C:\ProgramData\redshift\Data\OCIO -cs "Raw"
See the video below for a general demonstration of the same concepts.
| Texture Processor demo |
When auto-converting textures at render time, certain information is baked into the converted files based on how the texture is used. For example, the color space of the texture (e.g. sRGB) is used to correctly compute mip maps. When using the Texture Processor to manually pre-convert textures, the usage may need to be specified explicitly since it does not know how the texture is used in your scene.
If no OCIO config or gamma options are specified, the Texture Processor will assume linear gamma (-l) for floating point textures and sRGB gamma (s) for integer textures
If you don't know what options you should use for your textures, don't sweat, there's a solution for that. Since Redshift automatically converts textures based on how you set them up in your scene we can use this to figure out what texture processor options were used under those conditions — the answer can be found in the Redshift Log file.
First set up your scene and textures the way you like them, e.g. specifying the correct color space or the correct type of HDRI projection, and then hit render — this will trigger an automatic texture conversion if one has not already been done before for those textures. After that, navigate to the latest log file created by Redshift and look for information that is formatted like the following:
18:18:26 3589MB DEBUG:
Processing 3 textures
18:18:26 3589MB DEBUG:
Texture file 'C:\demo\texproc\textures\metal_tool_chest_nor_gl_4k.exr' conversion triggered, because: cache file was not found!
18:18:26 3589MB DEBUG:
- for pre-conversion, recommended TextureProcessor tool options are: -cs "Raw"
18:18:26 3589MB DEBUG:
Texture file 'C:\demo\texproc\textures\metal_tool_chest_diff_4k.jpg' conversion triggered, because: cache file was not found!
18:18:26 3589MB DEBUG:
- for pre-conversion, recommended TextureProcessor tool options are: -cs "sRGB"
18:18:26 3589MB DEBUG:
Texture file 'C:\demo\texproc\textures\artist_workshop_4k.exr' conversion triggered, because: cache file was not found!
18:18:26 3589MB DEBUG:
- for pre-conversion, recommended TextureProcessor tool options are: -isphere -cs "scene-linear Rec.709-sRGB"
18:18:28 3717MB DEBUG:
Time to process textures: 2.518601 seconds
In the example above, we can see that 3 different textures were processed because no cached or pre-converted texture was found. Helpfully, the recommended Texture Processor options for each texture are listed and these are based directly off of the settings that you specified in your 3D application. This is a great way to figure out what options you should use for your textures if you are ever unsure. For example, we can see that the "artist_workshop_4k.exr" file that was used with a dome light had the linear sRGB color space specified and the "-isphere" option should be used since the HDRI uses a spherical texture type.
| Option | Description |
| -path <path> | Specifies the output path to store the converted texture files. |
| -ociopath <path> | Specifies the OCIO config path used for converting color spaces. Unless specified, the OCIO environment variable path is used. |
| -cs <color space> | Specifies the color space to convert to from the OCIO config. |
| -useociorules | Uses OCIO file rules to automatically determine the color space. |
| -l | LEGACY, forces linear/raw gamma. (recommended for floating point textures) |
| -s | LEGACY, forces sRGB gamma (recommended for integer textures) |
| -p | Photometric IES data (for IES light profile types) |
| -wx | Used as a tiled texture with wrapping/repeats |
| -wy | Used as a tiled texture with wrapping/repeats |
| -u | The texture data will be stored uncompressed, which will use more disk space and bandwidth, but is necessary for enabling the mapped file feature. |
| -isphere | Image Base Light - Sphere projection |
| -ihemisphere | Image Base Light - Hemisphere projection |
| -imirrorball | Image Base Light - Mirrorball projection |
| -iangularmap | Image Base Light - Angular Map projection |
| -ocolor | Converts a texture to be used with a Sprite shader that derives opacity from color intensity |
| -oalpha | Converts a texture to be used with a Sprite shader that derives opacity from the alpha channel |
| -noskip | Disables the skipping of already converted textures if the processor thinks no data has changed. (By default, the processor will skip files that it determines have already been converted based on source, time stamps, usage, etc.) |
| -r | Recursively convert all textures found in the sub directory of the path |
| -log | Enables logging to a log file in the same directory as the pre-converted textures |