Basic Library Version: 9

LightWorks^® Lamps and Materials in GDL

Index

Introduction
Defining light sources
Defining materials
Mapping LightWorks names and GDL parameters

1. Introduction

This document gives a summary of making GDL objects for LightWorks^® rendering in ArchiCAD. It guides you in matching the LightWorks parameter names and values with the ones you can reach in GDL.

The whole creation process means defining light sources and materials containing LightWorks parameters. Look into this document for details.

You can use the following LightWorks shader types in ArchiCAD: Color, Reflectance, Transparency, Displacement, Texture-space, Foreground, Background, Light, Pipeline. Foreground and Background shaders cannot be specified in GDL these can be reached through the Photorendering User Interface.

The information in this document may only be used to access the LightWorks toolkit as integrated into ArchiCAD and in-conjunction with the ArchiCAD application. The LightWorks API is copyright © 1999,2000-2004 LightWork Design Ltd. All Rights Reserved. The LightWorks API may not be reproduced, copied or reverse-engineered.

2. Defining light sources

Making a LightWorks compatible light source is defining one LightWorks light shader in essence. The LightWorks rendering add-on uses the basic parameters you use in a generic ArchiCAD light command but you can add much more LightWorks-specific parameters. These parameters are described in the LightWorks documentation, the parameter name and value conversion is explained in the parameter-mapping section of this documentation.

Example code for definition of a spot lightsource:

DIM colorRGB[3]
colorRGB[1] = D
colorRGB[2] = E
colorRGB[3] = F
! scale (0-100) intensity to (0-10) exponentially
lwa_intensity = (2 ** (G * 0.03) - 1)

! simple spot light
light D * G/80, E * G/80, F * G/80,     ! RGB
        light_shadow,                   ! shadow on/off
        rLightCone,                     ! light cone radius
        halfAInnerCone, halfAOuterCone, ! cone angle inner - outer
        angleFalloff,                   ! angle falloff
        dist1, dist2,                   ! light start - stop
        distFalloff ADDITIONAL_DATA lwa_light = "LWA_LIgsspot",
        LWA_LIgsspot_radius = rLightCone,
        LWA_LIgsspot_coneangle = halfAOuterCone * 2,
        LWA_LIgsspot_conedeltaangle = halfAOuterCone - halfAInnerCone,
        LWA_LIgsspot_anglefalloff = angleFalloff,
        LWA_LIgsspot_start = dist1,
        LWA_LIgsspot_stop = dist2,
        LWA_LIgsspot_distancefalloff = distFalloff,
        LWA_LIgsspot_falloff = "LWA_inverse",
        LWA_LIgsspot_intensity =  lwa_intensity * 0.85,
        LWA_LIgsspot_intensityunits = "LWA_empirical",
        LWA_LIgsspot_color = colorRGB,
        LWA_LIgsspot_shadowtype = "LWA_soft",
        LWA_LIgsspot_shadowquality = 8,
        LWA_LIgsspot_shadowsoftness = 2,
        LWA_LIgsspot_shadowresol = 1024,
        LWA_LIgsspot_shadowtolerance = 0

3. Defining materials

Creating your own LightWorks ready materials you should consider the following:

A material definition may contain 6 shaders: color, reflectance, transparency, displacement, texture-space and pipeline.
Two of them are obligatory: color and reflectance.
Defining a material based on an ArchiCAD material you should know that both obligatory shaders are filled by the automatic conversion and two additional shaders may be added: transparency and displacement. The default generated texture-space shader is 'Z Plane'.
To disable an additional shader created by automatic conversion, declare it to be a 'none' shader.

Example 1: define own material - a lumpy colored glass

define material "Glass1" 0,
        cR, cG, cB,          ! RGB
        0.9, 0.95, 0.5, 0.9, ! amb., diff., specular, transp. coeff.-s
        0, 0,                ! shining, transparency att.
        0, 0, 0,             ! Specular RGB
        0, 0, 0,             ! Emission RGB
        0 ADDITIONAL_DATA LWA_reflectance = "LWA_RFglass",
        LWA_RFglass_specular = 0.5,
        LWA_RFglass_trans = 0.95,
        LWA_RFglass_mirror = 0.1,
        LWA_RFglass_roughness = 0.1,
        LWA_RFglass_refraction = 1.3,
        LWA_transparency = "LWA_TRnone",
        LWA_displacement = "LWA_DPrough",
        LWA_DPrough_amplitude = 0.05,
        LWA_DPrough_detail = 5

Example 2: define own material redefining reflectance of an inner material

define material "Glass2" BASED_ON matName PARAMETERS ADDITIONAL_DATA
        LWA_reflectance = "LWA_RFglass",
        LWA_RFglass_specular = 0.5,
        LWA_RFglass_trans = 0.9,
        LWA_RFglass_mirror = 0.4,
        LWA_RFglass_roughness = 0.1,
        LWA_RFglass_refraction = 1.3

Example 3: define own material deleting transparency from an inner material

define material "Mat3" BASED_ON matName PARAMETERS ADDITIONAL_DATA
        LWA_transparency = "LWA_TRnone"

4. Mapping LightWorks names and GDL parameters

The full knowledge base of creating an object for a LightWorks scene in GDL can be found in two sources: the LightWorks Programmers Reference and this documentation.

The description of shaders and their parameters can be found in the LightWorks documentation - except the ones with a name starting with 'gs'. Remember that you cannot reach the whole set of shaders from ArchiCAD which you can find in the LightWorks documentation. For the list of GS shaders refer the GS shaders document.

For the exact names and for class-grouping of shaders refer the parameter-mapping page of this documentation.

The general rules of mapping and naming are the following:

Enumerated types are replaced with text values.
Bitfield values are given with integer numbers.
Color and point types are replaced with array values - as described earlier.
Text-type and enumerated parameter values get an "LWA_" prefix.

Shader-class dependent parameter names begin with the following prefixes:

LWA_CO	Color shader
LWA_RF	Reflectance shader
LWA_TR	Transparency shader
LWA_DP	Displacement shader
LWA_TS	Texture-space shader
LWA_FG	Foreground shader
LWA_BG	Background shader
LWA_LI	Light shader
LWA_FL	Filter shader
LWA_TN	Tone shader
LWA_PP	Post-process shader
LWA_IN	Interface shader

Other parameters' names begin with the simple "LWA_" prefix.

Note that the Library Part Editor of ArchiCAD isn't capable to detect misspelled parameter names or values. Such problems appear first during photorendering; a message is written to the Report Window in this case if Full Report is set for the '3D and Calculation Process Check Controls' in the Work Environment options.
See an example where the script had a non-existent parameter and a misspelled parameter value:

Generated report

Steps of defining a material

First, we define a reflectance shader.
Open the parameter-mapping page at the Reflectance Shader Set part of the index.
Open the LightWorks Programmers Reference at the Reflectance index.
Find the reflectance shader which fits your needs most. Use both open documents for the available shaders and the full descriptions.
Let's take "plastic" for instance. Click it in both indexes.
Now you see the parameter descriptions and the default values in the LightWorks documentation. Let's assume you want to change the specular color of the plastic.
In the parameter-mapping page you can see that the plastic reflectance shader is called LWA_RFplastic in GDL and the "specular colour" parameter is called LWA_RFplastic_specularcolor. Now you have to remember that colors are given by arrays, this information is told in this document only.

This procedure creates the following additional parameter definitions:

DIM colorRGB[3]
colorRGB[1] = D
colorRGB[2] = E
colorRGB[3] = F

define material ...
        ... ADDITIONAL_DATA LWA_reflectance = "LWA_RFplastic",
        LWA_RFplastic_specularcolor = colorRGB

Passing color and point parameters

When adding a color or a point parameter to a lightsource, you have to create an array as you see it in the following contracted example:

DIM colorRGB[3]
colorRGB[1] = D
colorRGB[2] = E
colorRGB[3] = F

light D * G/80, E * G/80, F * G/80,
        ...
        distFalloff ADDITIONAL_DATA lwa_light = "LWA_LIgsspot",
        ...
        LWA_LIgsspot_color = colorRGB,
        ...

Enumerated and bitfield values

In both cases you have to look up the options fo the parameter in the parameter-mapping document.

In case of an enumeration-type parameter you just copy the name of the option into a string GDL parameter.

...
LWA_LIdistant_intensityunits = "LWA_kilolux",  ! Kilo-Lux option
...

In case of a bitfield parameter you can set some of the listed options. You pass it as the integer sum of the numbers of the options to set - as usual.

...
LWA_LIdistant_shadowtrans = 6,  ! set Interpolate and Displacement
...

LightWorks® Lamps and Materials in GDL