This light is a simple one to use, but wide-ranging in its potential scope. It has only two arguments, "area shader" and "goniometric shader". As the names suggest, the first argument expects to be passed a light shader of type "area" and the second a light shader of type "goniometric" . No other combination of shaders is valid.

The behaviour of the area goniometric shader is almost exclusively determined by the parameter settings of the shader passed in via the "area shader" argument. In fact ALL arguments to this "area shader" are used by the area goniometric shader, their usage being exactly the same as for a standard "area" light.

In addition the shader given via the "goniometric shader" argument is used to specify a photometric distribution for each point over the surface of the area goniometric shader. The distribution is interpreted as being the same at all points on the surface. The area goniometric shader therefore considers the settings of the following arguments to the "goniometric shader": "from", "to", "equator zero", "file name", "data", "emission", "normalise" and "free". Any other arguments which have been set for the "goniometric shader" will be ignored.

Note that if an invalid or NULL value is present for the "goniometric shader" argument then the light will default to behaving like a standard light of type "area". If, however, an invalid or NULL value is present for the "area shader" argument then it is not possible for the light to provide useful illumination.

The following example shows how to construct a simple area goniometric shader. This has an area light which is given a rectangular polygon (downwards facing). The accompanying goniometric light is given an emission distribution which is only non-zero for positive x directions. In these directions the emission function is constant so the resulting area goniometric light will behave like a standard goniometric light, but will only provide illumination in the positive x direction. See here for the complete example in .lwc format.

LtShader      area_gonio,
              area_shader,
              gonio_shader;
LtData        data,
              values[1];
LtProp        props[1];
LtStatus      status = LI_STATUS_OK;
LtPrim        area_prim;
LtPoint       positions[4],
              from,
              to,
              eq_zero;
LtEmissionSet es;
LtFloat       thetas[] = {0.0, 45.0, 90.0, 135.0, 180.0, 225.0, 
                          270.0, 315.0},
              phis[] = {0.0, 10.0, 20.0, 30.0, 40.0, 50.0, 60.0,
                        70.0, 80.0, 90.0},
              data_vals[] = {0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 
                             0.0, 0.0, 0.0,
                             0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
                             0.0, 0.0, 0.0,
                             0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
                             0.0, 0.0, 0.0,
                             0.0, 0.4, 0.6, 0.7, 1.0, 0.8, 0.7, 
                             0.1, 0.1, 0.0,
                             0.0, 0.4, 0.6, 0.7, 1.0, 0.8, 0.7, 
                             0.1, 0.1, 0.0,
                             0.0, 0.4, 0.6, 0.7, 1.0, 0.8, 0.7, 
                             0.1, 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, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0,
                             0.0, 0.0, 0.0};

/*
 * Firstly create all our shaders.
 */

area_gonio = LiShaderCreate(LI_SHADER_CLASS_LIGHT, 
                            "area goniometric");
area_shader = LiShaderCreate(LI_SHADER_CLASS_LIGHT, "area");
gonio_shader = LiShaderCreate(LI_SHADER_CLASS_LIGHT, "goniometric");
LiDataSetGenericPtr(&data, area_shader);
status = LiShaderSetArg(area_gonio, "area shader", &data);
LiDataSetGenericPtr(&data, gonio_shader);
status |= LiShaderSetArg(area_gonio, "goniometric shader", &data);

/*
 * Create an emission set.
 */

es = LiEmissionSetCreate(8, thetas, 10, phis, data_vals,
                         LI_EMISSION_SET_TYPE_3);
status |= LiEmissionSetPreProcess(es);

/*
 * Create geometry.
 */

LiPointInitialise(positions[0], 0.0, 0.0, 2.0);
LiPointInitialise(positions[1], 0.0, 1.0, 2.0);
LiPointInitialise(positions[2], 1.0, 1.0, 2.0);
LiPointInitialise(positions[3], 1.0, 0.0, 2.0);
props[0] = LI_PROP_VERT_WORLD;
LiDataSetFloatPtr(values, positions);
area_prim = LiPrimitiveCreatePolygon((LtNat32)4, (LtNat32)1, 
                                     props, values);

/*
 * Set relevant parameters for each shader.
 * Some example settings given for some of the parameters.
 */

LiDataSetGenericPtr(&data, area_prim);
status |= LiShaderSetArg(area_shader, "primitive", &data);
LiDataSetFloat(&data, (LtFloat)2000);
status |= LiShaderSetArg(area_shader, "intensity", &data);
LiDataSetEnum(&data, LI_INTEN_UNITS_LUMEN);
status |= LiShaderSetArg(area_shader, "intensity units", &data);
LiDataSetFloat(&data, (LtFloat)6500);
status |= LiShaderSetArg(area_shader, "colour temperature", &data);
LiDataSetBoolean(&data, TRUE);
status |= LiShaderSetArg(area_shader, "shadows", &data);
LiDataSetInt32(&data,  0);
status |= LiShaderSetArg(area_shader, "shadow resolution", &data);
LiDataSetFloat(&data, 0.5);
status |= LiShaderSetArg(area_shader, "min lod", &data);

LiPointInitialise(from, (LtFloat)0.5, (LtFloat)0.5, (LtFloat)0.5);
LiDataSetPoint(&data, from);
status |= LiShaderSetArg(gonio_shader, "from", &data);
LiPointIniatialise(to, (LtFloat)0.5, (LtFloat)0.5, (LtFloat)0.0);
LiDataSetPoint(&data, to);
status |= LiShaderSetArg(gonio_shader, "to", &data);
LiPointIniatialise(eq_zero, (LtFloat)0.0, (LtFloat)0.5, (LtFloat)0.5);
LiDataSetPoint(&data, eq_zero);
status |= LiShaderSetArg(gonio_shader, "equator zero", &data);
LiDataSetGenericPtr(&data, es);
status |= LiShaderSetArg(gonio_shader, "data", &data);