When creating an emission set, the assumption is that the data provided is distributed across the surface of a sphere and thus has the standard spherical (\theta, \phi) parameterisation. The arguments, num_thetas, thetas, num_phis and phis provide the set of directions for the emission set. Note that the angles provided are in degrees rather than radians. If fewer than 2 angles are given for the \theta or \phi arrays then the emission set is assumed to be constant for all \theta and/or \phi. If it is known that the data is, for example, independent of the \theta angle then the number of theta angles can be set to zero and the theta array parameter can be NULL.

The array data represents an array of LtFloats of length num_thetas * num_phis. This is the actual emission data. Values are ordered within the array by \theta and then by \phi. The array therefore contains data for all vertical, \phi, angles at the first horizontal, \theta, angle. This is followed by data values for all vertical angles at the second horizontal angle and so on. By default, the units of the actual data are assumed to be candela, although any scalar units are acceptable, and will only be relevant in certain cases (For example, if the user is interested in providing the magnitude of a goniometric light source, rather than simply its shape).

The extras parameter is a bitfield which allows useful additional information about the distribution to be passed in. Currently this information is limited to one of the following:

LI_EMISSION_SET_TYPE_3 is the default setting if no information is passed in via the extras parameter (i.e. it is 0). This indicates that the angles in the emission set are as follows: \theta varies from 0 up to 360 and \phi varies from 0 up to 180. LI_EMISSION_SET_TYPE_3 is equivalent to IESNA type C, CIE type C, CIBSE type C-gamma and EULUMDAT formats. Note that in some photometric formats setting the final angle for \theta or \phi to an angle less than 360 or 180 implies that some additional symmetry is present in the data. LiEmissionSetCreate does not currently provide special treatment for these cases.

LI_EMISSION_SET_TYPE_1 and LI_EMISSION_SET_TYPE_2 indicate that the angles in the emission set are as follows: \theta varies from -90 to +90 and \phi varies from -90 to +90. Again, setting the first angle for \theta to 0 rather than 90 implies there is additional symmetry present in the data, but this information is not currently used by LiEmissionSetCreate. There are two distinct types here (even though their angular distributions are the same) to distinguish between different photometric data formats and to allow for such formats to be treated differently in future. LI_EMISSION_SET_TYPE_1 is equivalent to IESNA type A, CIE type A and CIBSE type H-V. LI_EMISSION_SET_TYPE_2 is equivalent to IESNA type B and CIE type B.

LtEmissionSet the_set = (LtEmissionSet)NULL ;
LtFloat       thetas[] = { 0.0, 90.0, 180.0, 270.0 } ,
              phis[] = { 0.0, 10.0, 20.0, 30.0, 40.0, 
                        50.0, 60.0, 70.0, 80.0, 90.0 },
              data[] = { 0.0, 0.0, 0.0, 0.0, 0.0, 
                         0.0, 0.0, 0.0, 0.0, 0.0,
                         0.0, 1.0, 1.2, 1.5, 2.0, 
                         1.7, 1.4, 0.2, 0.1, 0.0,
                         0.0, 0.0, 0.0, 0.0, 0.0,
                         0.0, 0.0, 0.0, 0.0, 0.0,
                         0.0, 1.0, 1.2, 1.5, 2.0, 
                         1.7, 1.4, 0.2, 0.1, 0.0 } ;

/*
 * Create an emission set which throws light out to
 * the side.
 */

the_set = LiEmissionSetCreate( 4, thetas, 10, phis, data,
                               LI_EMISSION_SET_TYPE_3 ) ;