Corona XML maps format

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.

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>

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>

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>

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>

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>

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>

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

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

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)
}

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>

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>

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>

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>

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.

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>

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

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

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>

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>

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>

Creates a smooth UVW-mapped gradient

<map class=”Gradient”>
    <mode>u|v|radial</mode>
</map>

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>

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>

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

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

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>

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>

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>

Specific parameters for rawafake mode

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>