Map Data

Map Data 3.7

    map "name"
        declaration_name ( data )
    end map

    map "name"
        declaration_name ( mapfiles )
    end map

Map data is arbitrary data with positional information stored in the scene file or separate binary files. It is intended to pass point-like descriptions without any specific surface shape but properties like color or vector to the renderer or to shaders, 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 3D points. It can actually be any number between 1 and 6, for instance to define a 2-dimensional map, or 4-dimensional one.

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.

The map declaration is similar to regular shader declarations for its definition of the parameter set. This is a list of parameters of a supported type, called fields of a map. The dimension of the map is given by the first value of the parameter list, if omitted it defaults to 3 for 3D positional data.

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

where type can be one of

    integer
    scalar
    vector
    color
    transform
    array m_int integer
    array m_int scalar

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.

Here is an example of a 3D map declaration:

    declare map
        "particle_map"	(
            dim		3,
            vector      "direction",
            color       "color"
	)
    end declare

Note, that a 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, it can be used in a shader like any other shader parameter. The new simple type map has been added to the list of accepted types 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.

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

    map "candle_smoke"
        "particle_map" (
            { 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.