Procedural Textures

Procedural textures are textures generated by the engine on the basis of their text description. They can be used anywhere instead of normal textures.
Text description of procedural texture is set in standard place of texture path and filename. To identify that a procedural texture is used, the character "#" is set at the beginning of the string.
Usually the string consists of procedural texture type name and arguments on both sides enclosed in brackets, in format #(leftArgs)TypeName(rightArgs).

Textures may be generated procedurally and they take nearly no space on HDD but they still use space in video memory. Yet, if two materials use the exact same procedural texture string, the texture already existing in video memory is used and not duplicated - thus it may be important to try and avoid creating unnecessary similar textures.

⚠

• There cannot be any spaces or mathematical expressions within the string.
• Decimals always have to be preceded by a 0 (e.g. 0.5 instead of .5).
• Only double quotes " are supported within the string, single quotes ' are not:
  _object setObjectTexture [0, "#something(""text"")"]; // OK _object setObjectTexture [0, '#something("text")']; // OK _object setObjectTexture [0, "#something('text')"]; // not OK

Procedural Texture Types

Note that all texture types have in common the left-hand parameters list:

• format - texture color format (can be rgb, argb, ai, a, i)
• width - number of pixels in X, in power of two (e.g 1, 2, 4, 8, 16, 32, 64, 128 etc)
• height - number of pixels in Y, in power of two (e.g 1, 2, 4, 8, 16, 32, 64, 128 etc)
• mipmapsAmount - number of mipmaps to generate

Color

ⓘ

Always produces 1x1 texture, regardless of width and height provided

#(format,width,height,mipmapsAmount)color(r,g,b,a)

and

#(format,width,height,mipmapsAmount)color(r,g,b,a,textureType)

• r, g, b, a - texture channels (Red, Green, Blue, Alpha)
• textureType - texture type which match texture name ending without "_" (optional)

Examples:

#(rgb,8,8,3)color(1,0,0,1)
#(rgb,1,1,1)color(0.5,0.5,0.5,1)	// empty 1×1 detail map
#(rgb,1,1,1)color(0.5,0.5,1,1)		// empty 1×1 normal map
#(rgb,8,8,3)color(0.5,0.5,0.5,1,dt)
#(rgb,8,8,3)color(0.5,0.5,1,1,no)

Render To Texture

⚠

Render to Texture texture requires Picture-in-Picture (PiP) to be enabled in the Video options (see isPiPEnabled).

#(argb,512,512,1)r2t(surface,aspect)

• surface - The name that will later be used as reference in the camera script
• aspect - Aspect ratio of the image

ⓘ

Do not use capital letters when naming RTT surfaces.

Examples:

#(argb,512,512,1)r2t(rtt,1.0)
#(argb,512,512,1)r2t(rendersurface,1.333)

⚠

Aspect parameter ignored as late as 2.14

Perlin Noise

#(format,width,height,mipmapsAmount)perlinNoise(xScale,yScale,min,max)

• xScale - horizontal noise scale (typically a multiple of 256)
• yScale - horizontal noise scale (typically a multiple of 256)
• min - minimum value
• max - minimum value

Examples:

#(ai,512,512,9)perlinNoise(256,256,0,1)

Irradiance

#(format,width,height,mipmapsAmount)irradiance(specularPower)

• specularPower - specular strength

It is a values table that is used with per-pixel lighting. Modern shaders are not using this type of texture anymore.

Examples:

#(ai,32,128,1)irradiance(8)

Fresnel

#(format,width,height,mipmapsAmount)Fresnel(N,K)

• N - refractive index
• K - absorption coefficient

ⓘ

see Super shader - Fresnel function.

Example:

#(ai,64,64,1)Fresnel(1.3,7)

Fresnel Glass

#(format,width,height,mipmapsAmount)fresnelGlass()

Examples:

#(ai,64,64,1)fresnelGlass()

Water Irradiance

#(format,width,height,mipmapsAmount)waterIrradiance(specularPower)

• specularPower - specular strength

This texture main value is solely with special pixel shaders for water.

Examples:

Tree Crown

#(format,width,height,mipmapsAmount)treeCrown(density)

and

#(format,width,height,mipmapsAmount)treeCrownAmb(density)

for ambient lighting.

• density - defines how much light passes thought tree-top via the longest line segment

This texture is used only for diffuse lighting actually it just counts exponential function (v PS2 can be done easily w/o texture).

Parameter defines how much surrounding light passes into the defined point. It uses an exponential function of distance from circle boundary.

Examples:

#(ai,32,32,1)treeCrown(0.2)
#(ai,32,32,1)treeCrownAmb(0.5)

Point

#(format,width,height,mimapsAmount)point()

Create a white dot on a transparent background.

Examples:

#(rgb,64,64,1)point()

Dither

#(format,width,height,mipmapsAmount)dither(min,max)

• min - minimum value
• max - minimum value

The format has to be ai.

Examples:

#(ai,8,8,1)dither(0,150)

2.12

Text

Creates a text texture.

#(rgb,width,height,3)text(vAlign,hAlign,"FontName",fontSize,backgroundColor,textColor,"text")

• vAlign - from 0(top), 1(center), 2(bottom)
• hAlign - from 0(left), 1(center), 2(right)
• fontName - Available fonts
• fontSize - number
• backgroundColor - in format #RRGGBB or #RRGGBBAA
• textColor - in format #RRGGBB or #RRGGBBAA
• text - the text to display

Examples:

#(rgb,512,512,3)text(0,0,"Caveat",0.3,"#0000ff7f","#ff0000","Hallo\nWelt")

2.12

UI On Texture

Generates an UI Display and renders the result into a texture.

#(rgb,width,height,mipCount)ui("displayClassName","uniqueName","texType")

• displayClassName - case-sensitive, classname from Description.ext (Mission Config File) or config.cpp (Mod Config)
• uniqueName - a string to declare the display's unique name. Naming is the same as classnames (a-z, A-Z, 0-9, _)
• texType - (Optional, default "ca"?) see Texture Map Types

Examples:

#(rgb,1024,1024,1)ui("RscDisplayRenderTest","abc")
#(rgb,1024,1024,1)ui(RscDisplayMain,abc)

Related commands: displayUpdate, displayUniqueName

2.14

UI On Texture Advanced

Same as UI On Texture but has a different way of providing arguments and supports more advanced arguments. String values can be quoted in " or '. If no whitespace is in the string, quotes are not required.

#(rgb,width,height,mipCount)uiEx(paramName1:value1,paramName2:value2,...)

Currently supported parameters:

• display: String - the case-sensitive display's class name, from Description.ext (Mission Config File) or config.cpp (Mod Config)
• uniqueName: String - a string to declare the display's unique name. Naming is the same as classnames (a-z, A-Z, 0-9, _)
• texType: String - (Optional, default "ca"?) see Texture Map Types
• viewportX: Number - (Optional, default 0) horizontal offset for rendering viewport; can be used to only render specific section of the Display
• viewportY: Number - (Optional, default 0) vertical offset
• viewportW: Number - (Optional, default 1) width multiplier in percent
• viewportH: Number - (Optional, default 1) height multiplier
• bgColor: String - (Optional, default transparent #00000000) format #RRGGBB or #RRGGBBAA
• mipFilter: String - (Optional, default point) either point or linear

Examples:

#(rgb,2048,4096,1)uiEx(display:RscDisplayFieldManual,uniqueName:"test name with space and quotes")
#(rgb,2048,4096,1)uiEx(display:RscDisplayFieldManual,uniqueName:testName,viewportX:-0.5,viewportW:2,bgColor:#ff000000)