TEXTURES

TEXTURES is used to define composite textures in ZDoom. It is a text-based replacement format for the original TEXTURE1 and TEXTURE2 lumps. This lump was previously named HIRESTEX, but its name was changed to reflect its meaning. HIRESTEX lumps are still read but that name is deprecated as of now.

Composite textures

A composite texture, or multipatch texture, is, logically enough a texture composed of multiple patches. There are two parts in the texture's definition: the texture properties and the patches.

Texture properties

To define a new composite texture, use the texture keyword. Different graphics lumps can be defined in the same manner using their appropriate keyword. For most needs, "texture" is enough, but if different types of graphics have to have the same names, you can explicitly set their namespace with a different keyword. In any way, the format is the same:

texture [optional] Name, Width, Height (generic textures)
sprite [optional] Name, Width, Height (sprites)
graphic [optional] Name, Width, Height (menu graphics)
walltexture [optional] Name, Width, Height (wall textures)
flat [optional] Name, Width, Height (floors and ceilings)

Name is the name of the new composite texture/sprite. Width and Height are integers that define the width and height of the “canvas” for the composite image. Note that this is not the scaled size — those are defined by the X/YScale parameters within the texture/sprite parameter block. (See below)

The "optional" keyword can be used between the namespace-appropriate keyword and the texture name. If a texture is optional, there will be no warning messages if one of the patches it requires is missing, and the texture will instead not be created.

Following this line is an optional parameter block enclosed in curly-braces ({}) where different options and the patches that make up the composite image will be listed.

The following options are available:

• XScale <value>

Defines the amount by which to scale the width of the image. This uses an inverted scale. 2 scales the texture to 1/2 size, 4 scales to 1/4 size, 0.5 scales up by double, etc. It is not necessary to include this or YScale unless you're scaling the graphic, meaning, for example, "XScale 1.0" is simply a waste of space.

• YScale <value>

Defines the amount by which to scale the height of the image. This uses an inverted scale. 2 scales the texture to 1/2 size, 4 scales to 1/4 size, 0.5 scales up by double, etc.

• Offset <horz>, <vert>

Specifies the horizontal and vertical offset for a sprite image.

• WorldPanning

Specifies that texture offsets should be applied in world units, rather than by pixels in the texture. This allows scaled textures to be offset properly when replacing lower resolution textures in an existing map.

• NoDecals

Do not allow decals on this texture.

• NullTexture

The image will never actually be drawn. This duplicates the behavior of AASHITTY and other special textures.

Patch

In addition to texture-level options, the Patch keyword and block is used to add new patches to the composite image. A texture requires at least one patch to work. The formatting is as follows:

Patch Name, X-Origin, Y-Origin
Graphic Name, X-Origin, Y-Origin
Sprite Name, X-Origin, Y-Origin

Name is the name of the patch to add. X/Y-Origin define where in the “canvas” to place the patch, starting at the top-left pixel of the patch and drawing right and downward.

Instead of "patch", the "graphic" or "sprite" keyword can be used. The only practical difference is in namespace prioritizing, which is only relevant for PK3 archives since, in a WAD file, both patches and graphics are in the global namespace.

Similar to the texture construct, the Patch option can optionally have its own parameter block, also enclosed in curly-braces. These options are available within this block:

Warning: There are three important things to keep in mind: These options apply only to the patch itself during composition. The final texture composited from these patches is merely a collection of pixels which will not "remember" that they have been blended, translated or rotated. Alpha, Blend, and Style are only relevant for the composition of the texture. They have no effect on how the composited texture is rendered in-game. In particular, if there is no pixel information from another patch behind a blended or translucent patch, it will be blended with black. This cannot be used to create textures with varying amounts of translucency or multiple render styles! Blend and Translation are mutually incompatible and cannot be both used on the same patch.

• FlipX

Flips the patch right-to-left within the image.

• FlipY

Flips the patch upside down.

• UseOffsets

The patch's built-in offsets are subtracted from the X and Y origins, instead of being ignored as normal.

• Rotate <value>

Rotates the patch Clockwise within the image. Value is defined in degrees. Currently only multiples of 90 are valid (0/90/180/270). (Note: the origins of the patch do not change when rotated e.g. the patch is rotated in place around the center)

• Translation <string>

Applies a translation to this patch before inserting it in the composite image. <string> can be either one of the built in translations or a custom translation string consisting of the colors to remap from and to. See below.

• Blend <string color>[,<float alpha>]
• Blend <int r>,<int g>,<int b>[,<float alpha>]

This statement has two different effects depending on how it is used:
Specifying a color string and omitting the alpha parameter creates a custom colormap to translate the image to. This has the same effect as using Sector_SetColor, but applies the coloring directly to this patch.
If an alpha is supplied with the color, this blends a solid color into the patch, akin to screen tinting.
When using the second syntax, color values must be in the range from 0 to 255.

• Alpha <value>

Specifies the patch's translucency (0.0–1.0) when adding it to the image. Default is 1.0 (fully opaque). Use the Style property to control how the translucency is applied.

• Style <type>

Defines the render style for a translucent patch. See below.

There may be as many Patch statements and blocks present as needed to create the final composite image.

Translations

The colors of each patch can be translated independently as they are applied to the composite image.

To use one of the built in translation types, following the Translation property with one of:

• Desaturate, <amount>
• Blue
• Gold
• Green
• Ice
• Inverse
• Red

When using Desaturate, an additional integer between 1 and 31 is used to determine how much to desaturate the texture. 1 leaves the patch nearly unchanged, while 31 fully desaturates the patch into shades of grey.

In addition to these translation types, a custom translation can be defined using the same syntax as the DECORATE Translation property.

Translucency

Patches can be applied to the composite image using translucency. To do this, use the Alpha property to control how opaque the patch will be, and the Style property to control the type of translucency. Available values for Style are:

• Add

Causes the patch to be drawn with additive translucency, resulting in brightening effect.

• Copy

Renders the patch as normal and solid. This is the default if no Style is specified.

• CopyAlpha

This is the same as Copy, but does additional processing to respect a PNG's alpha channel.

• CopyNewAlpha

This works just like Copy except it multiplies each pixel's alpha channel by the specified Alpha property.

• Modulate

This has an extreme darkening effect, similar to Photoshop's "burn" style.

• Overlay

This is the same as CopyAlpha, except it only copies the patch's alpha channel where it has a higher alpha than what's underneath.

• ReverseSubtract

Same as subtract, but re-inverts the patch so it appears normal when being applied.

• Subtract

Subtracts the patch from patches below, resulting in a darkening effect. This implies inverting.

• Translucent

Applies regular translucency to the patch.

Examples

This creates a composite ladder texture by applying several copies of the same patch and rotating them 90 degrees. Bear in mind, in this example, that the X- and YScale properties are not necessary. They don't need to be defined unless you're up- or down-scaling an image.

texture ALADDER2, 72, 256
{
   XScale 1.0
   YScale 1.0
   Patch RW45_1, 0, 0
   {
      rotate 90
   }
   Patch RW45_1, 0, 64
   {
      rotate 90
   }
   Patch RW45_1, 0, 128
   {
      rotate 90
   }
   Patch RW45_1, 0, 172
   {
      rotate 90
   }
}

This example shows the CopyAlpha translucency effect being used in a 512x512 texture that's scaled to fit as if it were 128x128:

Texture SWEXPLUP, 512, 512
{
   // Switch Example
   // Up position
   XScale 4
   YScale 4
   Patch AG_512_2, 0, 0
   Patch MSW1_UP, 64, 288 { Style CopyAlpha }
}

Multiple TEXTURES lumps

While the #include feature is not available for the TEXTURES lump, you can have multiple TEXTURES lumps in your PK3. Simply give them different extensions besides .txt, or whatever your typical text extension is. For example, TEXTURES.tech, TEXTURES.wood, TEXTURES.hell, and so on. Organizing and categorizing your definitions like so makes it much easier to locate and modify entries.

Editor support

• Doom Builder 2 reads TEXTURES definitions and displays them in visual mode. Currently however, things such as flips, rotations, translations, blends, and images using long path names are not reflected.
• SLADE 3 also reads them and offers a visual texture editor.

Hi-res textures (Deprecated, but good for fast texture replacements)

Warning: Please consider using the more robust composite texture definition feature instead. These old HIRESTEX commands are considered deprecated and won't get updated anymore in the future.

To replace an original texture, sprite or graphic use:

remap texturename hireslumpname

And to define a new Hi-Res texture use:

define lumpname scaledwidth scaledheight

Using the HIRESTEX method is not needed for hires replacements. Simply putting graphics between HI_START/HI_END (WAD) or in a /Hires/ folder (PK3) will automatically scale them to the size of the graphics with the same name that they replace, and no text lump is required.