Back to the main pageGDL Syntax >>

Chapter 1. General Overview

GDL is a parametric programming language, similar to BASIC. It describes 3D solid objects like doors, windows, furniture, structural elements, stairs, and the 2D symbols representing them on the floor plan. These objects are called library parts.

Starting Out

The needs of your design, your background in programming and your knowledge of descriptive geometry will all probably influence where you start in GDL.

Do not start practicing GDL with complicated objectives in mind. Rather, try to learn GDL through experimenting step by step with all of its features to best utilize them to your advantage. Follow the expertise level recommendations below.

If you are familiar with a programming language like BASIC, you can get acquainted with GDL by observing existing scripts. You can also learn a lot by opening the library parts shipped with your software and taking a look at the 2D and 3D GDL scripts. Additionally, you can save floor plan elements in GDL format and see the resulting script.

If you are not familiar with BASIC, but have played with construction blocks, you can still find your way in GDL through practice. We advise trying the simplest commands right away and then checking their effect in the 3D window of the library part.

Several books and materials have been published on GDL and object library development.

Scripting

Library Part Structure

Every library part described with GDL has scripts, which are lists of the actual GDL commands that construct the 3D shape and the 2D symbol. Library parts also have a description for quantity calculations in ArchiCAD.

Master script commands will be executed before each script.

The 2D script contains parametric 2D drawing description. The binary 2D data of the library part (content of the 2D symbol window) can be referenced using the FRAGMENT2 command. If the 2D script is empty, the binary 2D data will be used to display the library part on the floor plan.

The 3D script contains a parametric 3D model description. The binary 3D data (which is generated during an import or export operation) can be referenced using the BINARY command.

The Properties script contains components and descriptors used in element, component and zone lists. The binary properties data described in the components and descriptors section of the library part can be referenced using the BINARYPROP command. If the properties script and the master script are empty, the binary properties data will be used during the list process.

The User Interface script allows the user to define input pages that can be used to edit the parameter values in place of the normal parameter list.

In the Parameter script, sets of possible values can be defined for the library part parameters.

The parameter set in the Parameters section are used as defaults in the library part settings when placing the library part on the plan.

In the Forward Migration script you can define the conversion logic which can convert placed instances of older elements.

In the Backward Migration script you can define a backward conversion to an older version of an element.

The Preview picture is displayed in the library part settings dialog box when browsing the active library. It can be referenced by the PICTURE and PICTURE2 commands from the 3D and 2D script.

ArchiCAD provides a helpful environment to write GDL scripts, with on-the-fly visualization, syntax and error checking.

Analyze, Deconstruct and Simplify

No matter how complex, most objects you wish to create can be broken down into building blocks of simple geometric shapes. Always start with a simple analysis of the desired object and define all the geometric units that compose it. These building blocks can then be translated into the vocabulary of the GDL scripting language. If your analysis was accurate, the combination of these entities will form the desired object. To make the analysis, you need to have a good perception of space and at least a basic knowledge of descriptive geometry.

Images/GDL_Images/general_windowrepr.png

Window representations with different levels of sophistication

To avoid getting discouraged early on in the learning process, start with objects of defined dimensions and take them to their simplest but still recognizable form. As you become familiar with basic modeling, you can increase the level of sophistication and get closer to the ideal form. Ideal does not necessarily mean complicated. Depending on the nature of the architectural project, the ideal library part could vary from basic to refined. The window on the left in the above illustration fits the style of a design visualization perfectly. The window on the right gives a touch of realism and detail which can be used later in the construction documents phase of the project.

Elaboration

Images/GDL_Images/general_deskelab.png

Depending on your purpose, your custom parametric objects may vary in elaboration. Custom objects for internal studio use may be less refined than the ones for general use or for commercial distribution.

If your symbols have little significance on the floor plan, or if parametric changes do not need to appear in 2D, then you can omit parametric 2D scripts.

Even if parametric changes are intended to be present in 2D, it is not absolutely necessary to write a parametric 2D script. You can perform parametric modifications in the 3D Script window or use the 3D top view of the modified object as a new symbol and save the modified object under a new name. Parametric changes to the default values will result in several similar objects derived from the original.

The most complex and sophisticated library parts consist of parametric 3D descriptions with corresponding parametric 2D scripts. Any changes in the settings will affect not only the 3D image of the object, but also its floor plan appearance.

Entry Level

These commands are easy to understand and use. They require no programming knowledge, yet you can create very effective new objects using only these commands.

Simple Shapes

Shapes are basic geometric units that add up to a complex library part. They are the construction blocks of GDL. You place a shape in the 3D space by writing a command in the GDL script.

A shape command consists of a keyword that defines the shape type and some numeric values or alphabetic parameters that define its dimensions.

The number of values varies by shape.

In the beginning, you can omit using parameters and work with fixed values only.

You can start with the following shape commands:

In 3D:

BLOCK, CYLIND, SPHERE, PRISM

In 2D:

LINE2, RECT2, POLY2, CIRCLE2, ARC2

Coordinate Transformations

Coordinate transformations are like moving your hand to a certain place before placing a construction block. They prepare the position, orientation and scale of the next shape.

Images/GDL_Images/general_blockcordtrans.png
BLOCK 1, 0.5, 0.5
ADDX 1.5
ROTY 30
BLOCK 1, 0.5, 0.5

The 3D window of the library part will optionally show you the home (G = global) and the current (L = local) position of the coordinate system for any object present.

The simplest coordinate transformations are as follows:

In 3D:

ADDX, ADDY, ADDZ, ROTX, ROTY, ROTZ

In 2D:

ADD2, ROT2

The commands starting with ADD will move the next shape, while the ROT commands will turn it around any of its axes.

Intermediate Level

These commands are a bit more complex, not because they expect you to know programming, but simply because they describe more complex shapes or more abstract transformations.

In 3D:

ELLIPS, CONE

POLY_, LIN_, PLANE, PLANE_

PRISM_, CPRISM_, SLAB, SLAB_, CSLAB_, TEXT

In 2D:

HOTSPOT2, POLY2_, TEXT2, FRAGMENT2

These commands usually require more values to be defined than the simple ones. Some of them require status values to control the visibility of edges and surfaces.

Coordinate Transformations

In 3D:

On top of the entry level transformations

MULX, MULY, MULZ, ADD, MUL, ROT

In 2D:

On top of the entry level transformations

MUL2

Example:

PRISM 4, 1, 3, 0,
        3,  3,
        -3, 3,
        -3, 0
ADDZ -1
MUL 0.666667, 0.666667, 1
PRISM 4, 1, 3, 0,
        3,  3,
        -3, 3,
        -3, 0
ADDZ -1
MUL 0.666667, 0.666667, 1
PRISM 4, 1, 3, 0,
        3,  3,
        -3, 3,
        -3, 0
Images/GDL_Images/general_blocksmul.png

The transformations starting with MUL will rescale the subsequent shapes by distorting circles into ellipses or spheres into ellipsoids. If used with negative values, they can be used for mirroring. The commands in the second row affect all three dimensions of space at the same time.

Advanced Level

These commands add a new level of complexity either because of their geometric shape, or because they represent GDL as a programming language.

In 3D:

BPRISM_BWALL_CWALL_XWALL_
CROOF_FPRISM_SPRISM_ 
EXTRUDEPYRAMIDREVOLVERULED
SWEEPTUBETUBEACOONS
MESHMASS  
LIGHTPICTURE  

There are shape commands in this group which let you trace a spatial polygon with a base polygon to make smooth curved surfaces. Some shapes require material references in their parameter list.

By using cutting planes, polygons and shapes, you can generate complex arbitrary shapes out of simple shapes. The corresponding commands are CUTPLANE, CUTPOLY, CUTPOLYA, CUTSHAPE and CUTEND.

In 2D:

PICTURE2, POLY2_A, SPLINE2, SPLINE2A

Flow Control and Conditional Statements

FOR - TO - NEXT

DO - WHILE, WHILE - ENDWHILE

REPEAT - UNTIL

IF - THEN - ELSE - ENDIF

GOTO, GOSUB

RETURN, END / EXIT

These commands should be familiar to anyone who has ever programmed a computer, but they are basic enough that you can understand them without prior programming experience.

They let you make repetitive script parts to place several shapes with little scripting, or let you make decisions based on prior calculations.

FOR i = 1 TO 5
    PRISM_ 8, 0.05,
            -0.5,  0,     15,
            -0.5,  -0.15, 15,
            0.5,   -0.15, 15,
            0.5,   0,     15,
            0.45,  0,     15,
            0.45,  -0.1,  15,
            -0.45, -0.1,  15,
            -0.45, 0,     15
    ADDZ 0.2
NEXT i
Images/GDL_Images/general_barsflow.png

Parameters

At this stage of your expertise, you can replace fixed numeric values with variable names. This makes the object more flexible. These variables are accessible from the library part’s Settings dialog box while working on the project.

Macro Calls

You are not limited to the standard GDL shapes. Any existing library part may become a GDL shape in its entirety. To place it, you simply call (refer to) its name and transfer the required parameters to it, just as with standard shape commands.

Expert Level

By the time you have a good understanding of the features and commands outlined above, you will be able to pick up the few remaining commands that you may need from time to time.

Note

The memory capacity of your computer may limit the file length of your GDL scripts, the depth of macro calls and the number of transformations.

You will find additional information on the above GDL commands throughout the manual. HTML format help files are also available with your software, giving a quick overview of the available commands and their parameter structure.

3D Generation

3D modeling is based on floating point arithmetics, meaning that there is no limit imposed on the geometric size of the model. Whatever size it is, it retains the same accuracy down to the smallest details.

The 3D model that you finally see on the screen is composed of geometric primitives. These primitives are stored in the memory of your computer in binary format, and the 3D engine generates them according to the floor plan you created. The metamorphosis between the architectural floor plan elements and the binary 3D data is called 3D conversion.

The primitives are the following:

Groups of these primitives are kept together as bodies. The bodies make up the 3D model. All of the features of 3D visualization - smooth surfaces, cast shadows, glossy or transparent materials - are based on this data structure.

The 3D Space

The 3D model is created in three-dimensional space measured by the x, y and z axes of a master coordinate system whose origin is called the global origin.

In Floor Plan view, you can see the global origin in the lower left corner of the worksheet if you open the program without reading a specific document. In addition, the global origin defines the zero level of all the stories referred to in a floor plan document.

When you place an object into the design, the floor plan position will define its location along the x and y axes of this master coordinate system. The location along the z axis can be set in the Object Settings dialog box or directly adjusted when placed in 3D. This location will be the base and the default position of the local coordinate system of the object. The shapes described in the script will be positioned with reference to this local coordinate system.

Coordinate Transformations

Every GDL shape is linked to the current position of the local coordinate system. For example, blocks are linked to the origin. The length, width and height of the block are always measured in a positive direction along the three axes. Thus, the BLOCK command requires only three parameters defining its dimensions along the axes.

How can you generate a shifted and rotated block? With the parameter structure of the BLOCK there is no way to do this. It does not have parameters for shift and rotation.

The answer is to move the coordinate system to the correct position before issuing the BLOCK command. With the coordinate transformation commands, you can pre-define its position and rotation around the axes. These transformations are not applied to the shapes already generated and are only effective on subsequent shapes.

The GDL Interpreter

When a GDL script is executed, the GDL interpreter engine will detect the location, size, rotation angle, user defined parameters and the mirrored state of the library part. It will then move the local coordinate system to the right position, ready to receive the GDL commands from the script of the library parts. Every time a command for a basic shape is read by the interpreter, it will generate the geometric primitives that make up that particular shape.

When the interpreter has finished, the complete binary 3D model will be stored in the memory, and you can perform 3D projections, fly-through renderings or sun studies on it.

ArchiCAD contains a pre-compiler and an interpreter for GDL. Interpretation of a GDL script uses the pre-compiled code. This feature increases speed of the analysis. If the GDL script is modified, a new code is generated.

Data structures converted from other file formats (e.g., DXF, Zoom, Alias Wavefront) are stored in a binary 3D section of the library parts. This section is referenced by the BINARY command from the GDL script.

The GDL Script Analysis

Users have no control over the order in which library parts placed on the floor plan are analyzed. The order of GDL script analysis is based on the internal data structure; moreover, Undo and Redo operations as well as modifications may influence that order. The only exceptions to this rule are special GDL scripts of the active library, whose names begin with "MASTER_GDL" or "MASTEREND_GDL".

Scripts whose name begins with "MASTER_GDL" are executed before a 3D conversion, before creating a Section/Elevation, before starting a list process and after loading the active library.

Scripts whose name begins with "MASTEREND_GDL" are executed after a 3D conversion sequence, after creating a Section/Elevation, when finishing a list process and when the active library is to be changed (Load Libraries, Open a project, New project, Quit).

These scripts are not executed when you edit library parts. If your library contains one or more such scripts they will all be executed in an order that is not defined.

MASTER_GDL and MASTEREND_GDL scripts can include attribute definitions, initializations of GDL user global variables, 3D commands (effective only in the 3D model), value list definitions (see the VALUES command) and GDL extension-specific commands. The attributes defined in these scripts will be merged into the current attribute set (attributes with same names are not replaced, while attributes originated from GDL and not edited in the program are always replaced).


GDL Reference Guide

Copyright© 2012 by GRAPHISOFT, all rights reserved. Reproduction, paraphrasing or translation without express prior written permission is strictly prohibited.