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>
| mode | 3dlocal 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 |
| rotateZ | rotation of the map in the UV-plane when using the UVW mode, in degrees |
| blur | Amount of blurring applied to the map |
| wrapModeX | Controls 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>
| removeToneMapping | If set to true, the texture will not be affected by VFB tone mapping controls |
| tonemappingShader > linearMultiplier | Linear multiplier the image gets multiplied with as a first step of the mapping |
| tonemappingShader > contrast | Amount of contrast. Must be a non-negative number, image is unaffected for 1 |
| tonemappingShader > saturation | Amount of color saturation. Must be in interval ←1, 1>, image is unaffected for 0 |
| tonemappingShader > brightness | Nonlinear brightness modification, in interval ←1, 1> |
| tonemappingShader > invertColors | If true, colors are inverted (in sRGB space) |
| tonemappingShader > gamma | Gamma 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 > path | Path to the LUT file. Currently supported formats are .cube and .3dl. If not present, the image is unaffected by LUT |
| lut > convertToLog | If true, the input color is converted to Log colorspace before LUT is applied |
| lut > opacity | Strength of the LUT. Must be in interval <0, 1>; 0 turns of LUT completely |
| lut > gamma | Exponent 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 master | Defines a tone mapping curve for a given RGB component (red, green, blue) or for all components (master) |
| colorCurve > * > interpolation | Defines the type of curve interpolation: either smooth cubic (PiecewiseCubic) or linear (PiecewiseLinear) |
| colorCurve > * > controlPoint | Control 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>
| item | Color or map being selected |
| frequency | Probability of selection of this item; does not have to add up to 1 |
| mixMin | Minimum amount of blending |
| mixMax | Maximum amount of blending |
| seed | Random seed |
| hueRandomization | Additional randomization of color hue of the resulting color, must be in [0, 1] |
| gammaRandomization | Additional 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>
| input | Input map |
| seed | Random seed |
| uOffset | Interval of offset in U coordinate |
| vOffset | Interval of offset in V coordinate |
| wRotation | Interval of rotation around W |
| uScale | Interval of scaling in U coordinate. Must be positive values |
| vScale | Interval of scaling in V coordinate. Must be positive values |
| lockScale | If 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>
| Axis | Which axis to use. This is usually 0 0 1 for camera rays |
| mode | Which geometry frame is the Axis defined in. |
| absValue | If 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>
| maxRadius | Radius of the rounded corners effect |
| mappedRadius | If used, then this map will modulate the MaxRadius parameter |
| samples | Optional 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/v | Creates a gradient in the u/v axis by directly returning the u/v value as intensity |
| radial | Creates 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>
| mappedDistance | If used, this map will modulate the maxDistance. |
| samples | Number of ray tracing samples to make in each evaluation, influences the noise-speed ratio. |
| phongExponent | How concentrated should be the rays around normal. |
| mixExponent | Sets balance between occluded and unoccluded color (works similarly to gamma correction). |
| normalMode | Where to compute the effect - on the outside/inside of the object. |
| offset | Constant 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. |
| excludeMode | If 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>
| worldSpace | If true, then edgeWidth and VertexWidth are in world units. If false, they are in screen units (projected pixels). |
| allEdges | False 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>
| size | determines 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>
| multiplier | Overal intensity multiplier. |
| turbidity | Amount of haze in the atmosphere. Has to be between 1.7 and 10. |
| groundColor | Color 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. |
| horizonBlur | Simulates aerial perspective by blurring the line between sky and horizon. |
| mode | Which 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:
| zenith | Sky color at zenith. |
| horizon | Sky color at the horizon. |
| sunGlow | The amount of glow of the sky very near the sun. Value between 0 and 1 is required. |
| sunSideGlow | The amount of glow of the sky in the general direction of the sun. Value between 0 and 1 is required. |
| sunBleed | Intensity of the sun tint. Value between 0 and 1 is required. |
| sunFalloff | Slope 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>
| gamma | If present, overrides default gamma handling (2.2 for LDR and 1.0 for HDR formats) |