Table of Contents

See Corona XML materials format for basic info on the format. Here we will only list specific map definitions, but they still need to be contained in the <mtlLib><mapDefinition>… structure as outlined in the main article.

Shared utilities

UV mapper


This object is no a standalone map in itself, but it modifies UVW mapping of other maps by for example switching between 2D and 3D mapping, or by stretching or offsetting the UVW coordinates.

Only some maps have UVW mapping. For example noise and bitmap have mapping and can be manipulated by providing a UV mapper, but Ambient occlusion map cannot be modifies, since its geometric effect does not depend on UVW coordinates. Any map can contain UV mapper definition: <map><uvMap>…</uvMap>…</map>. If a map has a custom UV mapper defined, then also all its child nodes have the same UV mapper (except for referenced maps).

Definition of UV mapper is:

<uvMap>
    <mode>uvw|3dworld|3dlocal|forceEnviro</mode>
    ?<mapChannel>[int]</mapChannel>
    ?<scale>[XYZ]</scale>
    ?<offset>[XYZ]</offset>
    ?<rotateZ>[float - deg]</rotateZ>
    ?<enviroRotate>[float - deg]</enviroRotate>
    ?<enviroMode>spherical|screen|dome|cross|mirrorBall</enviroMode>
    ?<wrapModeU>clamp|repeat|none</wrapModeU>
    ?<wrapModeV>clamp|repeat|none</wrapModeV>
    ?<blur>[float]</blur>
    ?<useRealWorldScale>[bool]</useRealWorldScale>
    ?<dome>
        <origin>[XYZ]</origin>
        <radius>[float]</radius>
        <cameraHeight>[float]</cameraHeight>
    </dome>    
</uvMap>
mode3dlocal differs from 3dworld in that in the local mode the mapping “sticks” to the object even when it is rotated/moved, while in 3dworld the mapping “flows” on the object if it is moved. forceEnviro means that the map will be evaluated as environment-mapped (spherical or screen, see enviroMode option), even when it is applied on a geometry
rotateZrotation of the map in the UV-plane when using the UVW mode, in degrees
blurAmount of blurring applied to the map
wrapModeXControls what happens outside of the 0-1 UVW range. Clamp means that the border pixels will be returned outside of the interval. Repeat means that the entire map will be repeated. None means that black will be returned

Alpha-mixing map with constant value

If a slot has [RGB]|[map] or [float]|[map] content, it can also contain both. In that case the map's alpha channel will be evaluated (if there is any), and will be used for blending with the constant value. Example of red color mixing with bitmap:

<diffuse>
1 0 0 
<map class="Texture">
    ...
</map>
</diffuse>

Color mapping/transform maps

Normal


Transforms any input map to a normal map - meaning it will be interpreted as normal map instead of height map when in bump slot.

<map class="Normal">
    <child>[map]</child>
</map>

Channel


Maps channels on the output to the channels on the input. Output channels are R,G,B,Alpha and Mono. Individual mapping options for each channel are:

  • R - Red channel of the input

  • G - Green channel of the input

  • B - Blue channel of the input

  • A - Alpha channel of the input

  • RgbIntensity - Average of Red, Green and Blue of the input

  • One - Output channel is set to the value of 1.0

By default an output channel is mapped to the corresponding input channel. Mono is mapped to the RgbIntensity.

<map class="Channel">
    <rSource>R|G|B|A|RgbIntensity|One</rSource>
    <gSource>R|G|B|A|RgbIntensity|One</gSource>
    <bSource>R|G|B|A|RgbIntensity|One</bSource>
    <alphaSource>R|G|B|A|RgbIntensity|One</alphaSource>
    <monoSource>R|G|B|A|RgbIntensity|One</monoSource>
    <child>[map]</child>
</map>


For example, you could swap green and blue channels of the input (child) map using the following snippet.

<map class="Channel">
    <gSource>B</gSource>
    <bSource>G</bSource>
    <child><map>...</map></child>
</map>

Curve


Remaps each color component of the child map values according to a curve. Defined by multiple (2+) control points. Linearly interpolated between control points, constant outside of defined ranges.

<map class="Curve">
    <child>[RGB]|[map]</child>
 
    +<point position="[float]">[float]</point>
</map>


Example: this example clamps all output to be at most 0.5:

<map class="Curve">
    <child><map>...</map></child>
 
    <point position="0">0</point>
    <point position="0.5">0.5</point>
    <point position="1">0.5</point>
</map>

Interpolation


Similar to curve, but evaluates the child map as mono, and then uses the mono input to interpolate between RGB values, which can be also mapped.

<map class="Interpolation">
    <child>[RGB]|[map]</child>
 
    +<point position="[float]">[RGB]|[map]</point>
</map>

Fresnel


Applies a fresnel curve on mono input provided by a child node.

<map class=”Fresnel”>
    <ior>[float]</ior>
    <child>[RGB]|[map]</child>
</map>

ToneMap


Applies some predefined tone mapping operations on child map.

<map class=”ToneMap”>
    <child>[RGB]|[map]</child>
    ?<multiplier>[RGB]</multiplier>
    ?<alphaMultiplier>[float]</alphaMultiplier>
    ?<offset>[RGB]</offset>
    ?<invert>[bool]</invert>
    ?<clamp>[bool]</clamp>
    ?<abs>[bool]</abs>
    ?<removeToneMapping>[bool]</removeToneMapping>
</map>


Result:

output = offset + input*multiplier
if(invert) {
    output = 1 - output
}
if(abs) {
    output = abs(output)
}
if(clamp) {
    output = clamp(output, 0, 1)
}
if(removeToneMapping) {
    output = inverseImageToneMapping(output)
}

ColorCorrectMap


Applies color correction operations on child map.

<map class=”ColorCorrectMap”>
    <child>[RGB]|[map]</child>
    ?<removeToneMapping>[bool]</removeToneMapping>
    ?<tonemappingShader>
        ?<linearMultiplier>[RGB]</linearMultiplier>
        ?<contrast>[float]</contrast>
        ?<saturation>[float]</saturation>
        ?<brightness>[float]</brightness>
        ?<invertColors>[bool]</invertColors>
        ?<gamma>[float]</gamma>
        ?<lut>
            <path>[filename]</path>
            ?<convertToLog>[bool]</convertToLog>
            ?<opacity>[float]</opacity>
            ?<gamma>[float]</gamma>
        </lut>
        ?<colorCurve>
            <red>
                <interpolation>PiecewiseCubic|PiecewiseLinear</interpolation>
                *<controlPoint>[XY]</controlPoint>
            </red>
            <green>
                <interpolation>PiecewiseCubic|PiecewiseLinear</interpolation>
                *<controlPoint>[XY]</controlPoint>
            </green>
            <blue>
                <interpolation>PiecewiseCubic|PiecewiseLinear</interpolation>
                *<controlPoint>[XY]</controlPoint>
            </blue>
            <master>
                <interpolation>PiecewiseCubic|PiecewiseLinear</interpolation>
                *<controlPoint>[XY]</controlPoint>
            </master>
        </colorCurve>
    </tonemappingShader>
</map>
removeToneMappingIf set to true, the texture will not be affected by VFB tone mapping controls
tonemappingShader > linearMultiplierLinear multiplier the image gets multiplied with as a first step of the mapping
tonemappingShader > contrastAmount of contrast. Must be a non-negative number, image is unaffected for 1
tonemappingShader > saturationAmount of color saturation. Must be in interval ←1, 1>, image is unaffected for 0
tonemappingShader > brightnessNonlinear brightness modification, in interval ←1, 1>
tonemappingShader > invertColorsIf true, colors are inverted (in sRGB space)
tonemappingShader > gammaGamma transformation (output = input^(1/gamma)), in interval <0.01, 10>. 1 is neutral (no change) value. Note that since texturing is done entirely in linear color space, the value 2.2 does not have any special meaning here, and is not the default/correct/required value. You do not need to set this to 2.2 to get “correct” result - use it purely as artistic control over texture midpoint brightness
lut > pathPath to the LUT file. Currently supported formats are .cube and .3dl. If not present, the image is unaffected by LUT
lut > convertToLogIf true, the input color is converted to Log colorspace before LUT is applied
lut > opacityStrength of the LUT. Must be in interval <0, 1>; 0 turns of LUT completely
lut > gammaExponent of gamma transform baked into LUT. Default value 2.2 corresponds to LUT being applied in sRGB space. Note that if convertToLog is true, gamma is applied before log transformation
colorCurve > red green blue masterDefines a tone mapping curve for a given RGB component (red, green, blue) or for all components (master)
colorCurve > * > interpolationDefines the type of curve interpolation: either smooth cubic (PiecewiseCubic) or linear (PiecewiseLinear)
colorCurve > * > controlPointControl points that define the curve shape. Each point is two dimensional and must fit in <{0,0},{2,2}>

Mixing

Multi


Select one of the sub-maps as output based on randomization by selected feature. MixMin and MixMax, if used, enable partial blending between the randomly selected submap and all other maps in the same point.

<map class=”Multi”>
    <mode>Material|MaterialId|Instance|Primitive</mode>
 
    +<slot>
        <item>[RGB]|[map]</item>
        <frequency>[float]</frequency>
    </slot>
 
    ?<mixMin>[float]</mixMin>
    ?<mixMax>[float]</mixMax>
    ?<seed>[int]</seed>
    ?<hueRandomization>[float]</hueRandomization> 
    ?<gammaRandomization>[float]</gammaRandomization>
 
</map>
itemColor or map being selected
frequencyProbability of selection of this item; does not have to add up to 1
mixMinMinimum amount of blending
mixMaxMaximum amount of blending
seedRandom seed
hueRandomizationAdditional randomization of color hue of the resulting color, must be in [0, 1]
gammaRandomizationAdditional randomization of gamma exponent of the resulting color, must be in [0, 1]


UvwRandomizer


Modifies UWV coordinates of the input map based on given randomization mode; works similarly to MultiMap. All randomization parameters have a minimal and maximal value and a step. If the step is 0, the selected value of the parameter can be any real number within the interval. For positive value of the step, the selected value is (from + k * step) for some integer k. The step cannot be negative.

<map class=”UvwRandomizer”>
    <mode>Material|MaterialId|Instance|Primitive</mode>
 
    <input>[map]</input>
 
    ?<seed>[int]</seed>
    ?<uOffset>
       <from>[float]</from>
       <to>[float]</to>
       <step>[float]</step>
    </uOffset>
    ?<vOffset>
       <from>[float]</from>
       <to>[float]</to>
       <step>[float]</step>
    </vOffset>
    ?<wRotation>
       <from>[float - deg]</from>
       <to>[float - deg]</to>
       <step>[float - deg]</step>
    </wRotation>
    ?<uScale>
       <from>[float]</from>
       <to>[float]</to>
       <step>[float]</step>
    </uScale>
    ?<vScale>
       <from>[float]</from>
       <to>[float]</to>
       <step>[float]</step>
    </vScale>
 
    ?<lockScale>[bool]</lockScale>
</map>
inputInput map
seedRandom seed
uOffsetInterval of offset in U coordinate
vOffsetInterval of offset in V coordinate
wRotationInterval of rotation around W
uScaleInterval of scaling in U coordinate. Must be positive values
vScaleInterval of scaling in V coordinate. Must be positive values
lockScaleIf true, the scaling is uniform, i.e. the same in U and V (based on the value of U parameter). Otherwise, U and V are scaled independently.

RaySwitcher


Selects one of submaps during shading based on incident ray type. If one of the types is not defined, “base” slot will be used instead for that ray type.

<map class=”RaySwitcher”>
    <base>[RGB]|[map]</base>
    ?<reflect>[RGB]|[map]</reflect>
    ?<refract>[RGB]|[map]</refract>
    ?<direct>[RGB]|[map]</direct>
</map>

Mix


Mixes two maps with selected operation:

<map class=”Mix”>
    <a>[float]|[map]</a>
    <b>[float]|[map]</b>
    ?<amountB>[float]|[map]</amountB>
    <operation>mul|add|sub|mix|...TODO</operation>
</map>


Result:

if operation == mix: 
    output = eval(a)*(1-eval(amountB)) + eval(b)*eval(amountB)
else if operation == mult: 
    output = eval(a) * eval(b)
else if operation == add: 
    output = eval(a) + eval(b)
else if operation == sub: 
    output = eval(a) - eval(b)
else: 
    ERROR


Addition also works on bump maps.

FrontBack


Returns either “front” submap when ray hits the geometry from its front side, and “back” submap otherwise.

<map class=”FrontBack”>
    <front>[RGB]|[map]</front>
    <back>[RGB]|[map]</back>
</map>

Geometry maps

Data


Returns some geometry data directly re-casted as color values.

<map class=”Data”>
    <mode>UVW|shadingNormal|geometryNormal|dotProduct|zDepth|dUvw</mode>
</map>

Falloff


Returns angle between a normal and specified axis - white for facing, black for grazing edges, negative for back-facing.

<map class=”Falloff”>
    <mode>view|local|world</mode>
    <axis>[XYZ]</axis>
    ?<absValue>[bool]</absValue>
</map>
AxisWhich axis to use. This is usually 0 0 1 for camera rays
modeWhich geometry frame is the Axis defined in.
absValueIf true, absolute value of negative values will be used.


Example: Creates a dot product shading between shading normal and camera ray direction:

<map class=”Falloff”>
    <mode>view</mode>
    <axis>0 0 1</axis>
</map>

Round Edges


Special map for use in bump slot, which simulates rounded edges/corners by perturbing shading normal.

<map class=”RoundEdges”>
    <maxRadius>[float]</maxRadius>
    ?<samples>[int]</samples>
    ?<mappedRadius>[map]</mappedRadius>
</map>
maxRadiusRadius of the rounded corners effect
mappedRadiusIf used, then this map will modulate the MaxRadius parameter
samplesOptional number of samples to take. It influences the render noise and speed

Gradient


Creates a smooth UVW-mapped gradient:

<map class=”Gradient”>
    <mode>u|v|radial</mode>
</map>
u/vCreates a gradient in the u/v axis by directly returning the u/v value as intensity
radialCreates a radial gradient in the 0-1 UVW square with center in 0.5, 0.5

Ao


Creates the ambient occlusion (darkening in corners) effect. Returns 0 for completely unoccluded and 1 for completely occluded geometry.

<map class=”Ao”>
    <maxDistance>[float]</maxDistance>
    ?<mappedDistance>[map]</mappedDistance>
    ?<samples>[int]</samples>
    ?<phongExponent>[float]</phongExponent>
    ?<mixExponent>[float]</mixExponent>
    ?<normalMode>outside|inside|both</normalMode>
    ?<offset>[XYZ]</offset>
    ?<excludeMode>list|same|other</excludeMode>
    ?<includeExclude>[includeList]</includeExclude>
</map>
mappedDistanceIf used, this map will modulate the maxDistance.
samplesNumber of ray tracing samples to make in each evaluation, influences the noise-speed ratio.
phongExponentHow concentrated should be the rays around normal.
mixExponentSets balance between occluded and unoccluded color (works similarly to gamma correction).
normalModeWhere to compute the effect - on the outside/inside of the object.
offsetConstant offset in world space added to all generated rays. This can be used to shift the distribution of rays in one constant direction (typically up or down to create for example water weathering.
excludeModeIf present this can be used to exclude some objects from consideration when computing occlusion. “Other” means that occlusion by other objects will be disregarded and only same object occlusion will be used. “Same” is the opposite, with occlusion by the same object as hit point ignored. “List” means that an include/exclude list will be used.

Wire


Wire shader, which mixes 3 colors or maps - base, color for geometry edges between triangles, and color for geometry vertices. If edge/vertex parameters are not included, then the edges/vertices will not be visible in the result.

<map class=”Wire”>
    <base>[RGB]|[map]</base>
    <edge>[RGB]|[map]</edge>
    <vertex>[RGB]|[map]</vertex>
    <edgeWidth>[float]</edgeWidth>
    <vertexWidth>[float]</vertexWidth>
    <worldSpace>[bool]</worldSpace>
    <allEdges>[bool]</allEdges>
    <falloff>[float]</falloff> (1.6+)
</map>
worldSpaceIf true, then edgeWidth and VertexWidth are in world units. If false, they are in screen units (projected pixels).
allEdgesFalse by default and if that is the case then only the base mesh edges are visualized. By base mesh edges we mean those the user see in the content creation tool. All edges created by Corona (for example in displacement) remain hidden.

Generators

Solid


This special map always return constant value. It is optimized to have zero runtime overhead:

<map class=”Solid”>
    [RGB]|[float]
</map>

Checker


Produces black and white checker based on mapping (default is UVW, but can be altered with a UV mapper).

<map class=”Checker”>
    <size>[float]</size>
</map>
sizedetermines the size of tiles

Noise


Generates black and white noise. Can have uvmap:

<map class=”Noise”>
    <type>perlin|cellular|...TODO</type>
    <size>[float]</size>
optional: <levels>[float]</levels>
optional:   <uvmap>...</uvmap>
optional:   <phase>[float]</phase>
</map>

Sky


Used for environments, evaluates the Hosek & Wilkie sky model to compute physically correct sky dome.

<map class=”Sky”>
    <groundColor>[RGB]</groundColor>
    ?<mode>preetham|rawafake|hosek</mode>
    ?<turbidity>[float]</turbidity>    
    ?<multiplier>[float]</multiplier>
    ?<horizonBlur>[float]</horizonBlur>
    ?<skyAffectGround>[bool]</skyAffectGround>
    ?<rawafake>
        ?<zenith>[RGB]</zenith>
        ?<horizon>[RGB]</horizon>
        ?<sunGlow>[float]</sunGlow>
        ?<sunSideGlow>[float]</sunSideGlow>
        removed in 1.7: <sunBleed>[float]</sunBleed>
        removed in 1.7: <sunFalloff>[float]</sunFalloff>
    </rawafake>
</map>
multiplierOveral intensity multiplier.
turbidityAmount of haze in the atmosphere. Has to be between 1.7 and 10.
groundColorColor of the ground - used for rays looking downwards (with negative Z component). Additionally, if skyAffectGround is true, then this color is also used to influence the sky color on horizon.
horizonBlurSimulates aerial perspective by blurring the line between sky and horizon.
modeWhich sun/sky model to use (preetham - old physically-based model, very inaccurate near horizon; rawafake - ad-hoc model by Rawalanche, with customizable color; hosek - improved physically-based model by Hosek&Wilkie, very accurate, used by default).

Specific parameters for rawafake mode:

zenithSky color at zenith.
horizonSky color at the horizon.
sunGlowThe amount of glow of the sky very near the sun. Value between 0 and 1 is required.
sunSideGlowThe amount of glow of the sky in the general direction of the sun. Value between 0 and 1 is required.
sunBleedIntensity of the sun tint. Value between 0 and 1 is required.
sunFalloffSlope of change of suns color.

Texture


Regular image texture:

<map class=”Texture”>
    <image>[filename]</image>
 
    ?<gamma>[float]</gamma>
    ?<bumpStrength>[float]</bumpStrength>
    ?<interpolation>bilinear|bicubic|nearest</interpolation>
 
    ?<crop>
        <startX>[float]</startX>
        <startY>[float]</startY>
        <endX>[float]</endX>
        <endY>[float]</endY>
    </crop>
 
    ?<placement>
        <startX>[float]</startX>
        <startY>[float]</startY>
        <endX>[float]</endX>
        <endY>[float]</endY>
    </placement>
 
</map>
gammaIf present, overrides default gamma handling (2.2 for LDR and 1.0 for HDR formats)