Map Data

map "name"
    declaration_name ( data )
end map

map "name"
    declaration_name ( mapfiles )
end map

Map data is arbitrary data of known type coupled with positional information stored in the scene file, or separate binary files. In other words, it carries data which is attached to a point in space but not necessarily related to a surface shape or other existing geometric representations in mental ray, therefore often referred to as a point cloud. Such a map can be generated and used by custom shaders to implement special effects. More importantly, it allows external applications to pass such information efficiently to mental ray, like global illumination information, particle systems, or fluid density grids.

The dimension of a map is the dimension of the position information of its elements: the dimension 3 means that the elements are points in 3D space. mental ray supports dimensions between 1 and 6, for instance to define a 2-dimensional map, or 4-dimensional one.

The map declaration determines the layout of the data attached to the points. The syntax is similar to regular shader declarations and the way it defines a set of parameters. It lists a number of parameters as a pair of a name and associated type, called fields of a map. The dimension of the map is given by an optional first field in the list. If this field is omitted it defaults to 3 for 3D positional data.

declare map "name" (
    [dim count_int ,]
    type "field_name",
    type "field_name",
    ...
    type "field_name"
    )
end declare

where type can be one of

[ global ] integer
[ global ] scalar
[ global ] vector
[ global ] color
[ global ] transform
[ global ] array integer n_int
[ global ] array scalar n_int

 global string n_int

to specify 32-bit integers, single-precision floats, 3-component float vectors, 4-component float colors and 4x4 float matrices, as well as fixed size arrays of integers and floats. If the type declaration is prefaced with the global keyword then the field value is stored once per map only, otherwise the field values are stored per point. A string may be attached to a map as a global value, for example to store informal text for identification.

Here is an example of a 3D map declaration:

declare map
    "particle_map" (
        dim                3,
        global integer     "version",
        global string 512  "comment"
        vector             "direction",
        color              "color",
)
end declare

Note The position field does not need to be declared since it is implicitly existing and in this case has a dimension of 3.

Once a map is declared, the declaration name can be used to create an actual map and set its values. This map definition, also known as a map instance, can be passed to a shader like any other shader parameter using the type map available for shader declarations. This allows to declare a shader parameter as a single map, or as an array of maps similar to light lists, for instance.

There are two ways to define map data:

as data list of items for each point. This is a sequence of ASCII values of a supported type and layout that matches the declaration, as follows:
```
{ field₁, ...field_m }₁ [ ,... { field₁, ...field_m }_n ]
```
The supported data types include integer and float numerical values given in arbitrary combinations or as pre-defined mental ray data types like vector or color, see declaration for details.
as mapfiles to specify a file name or a list of file names.
```
[ "mapfile₁" [, ..."mapfile_n"] ]
```
The files contain binary map data in a data layout according to the declaration. The file(s) will be opened and its binary contents are read into memory upon access during rendering.

An actual instance of map data according to the declaration example above might look like this:

map "candle_smoke"
    "particle_map" (
        { global 1, "A map example" },
        { 1.23 2.1 3.4 , 0.0 1.0 0.0 , 0.1 0.1 0.1 1.0 },
        { 2.56 1.87 2 , 0.707 0.707 0.0 , 1.0 0.5 0.3 1.0 },
        ...
    )

And in case the data would be provided by external files:

map "candle_smoke"
    "particle_map" ( [ "my_data.pm" ] )

Shaders can access a map if they evaluate a parameter of type map. Shaders may create a map and store it into a file on disk for subsequent uses in different frames or renderings. A typical application is the implementation of a point cache for performance optimizations of a custom rendering effect.

The current implementation of map data has some known limitations.