@database Worldbuilder.guide

@$VER: Worldbuilder V1.00 - by Andrea Galimberti - (C) Brighting Brain Brothers

This guide file has been created using AutoGuide V1.05 - By Fabio Rotondo (fsoft@intercom.it).

@node main "AFC Module: Worldbuilder / Main"


              ** Worldbuilder V1.00 - Original By Andrea Galimberti **

                         Part of Amiga Foundation Classes


    @{" Introduction   " LINK world_intro} Important: don't skip this as usual.
    @{" Author(s) Info " LINK author}


    Requires: @{" nodemaster " LINK "nodemaster.guide/Main"}

    Base: $8005

    Sections:    @{" Worldbuilder methods " LINK world_methods}
                 @{" Object_obj methods   " LINK world_o_methods}
                 @{" Procedures           " LINK world_procedures}


                 @{" ERROR TABLE        " LINK Error_Table}
@endnode

@node world_methods "AFC module: Worldbuilder methods"

    Worldbuilder methods:

    COMMANDS                          BRIEF DESCRIPTION
    -----------------------------------------------------------------------

    @{" worldbuilder()                   " LINK worldbuilder} Initializes a world

    @{" addobj()                         " LINK world_addobj} Create and add an object
    @{" setobj()                         " LINK world_setobj} Only add an existing object
    @{" getobj()                         " LINK world_getobj} Get a specified object
    @{" delobj()                         " LINK world_delobj} Delete object
    @{" unlinkobj()                      " LINK world_unlinkobj} Remove an object
    @{" clearobj()                       " LINK world_clearobj} Clear an object

    @{" setvertex()                      " LINK world_setvertex} Add vertex to object
    @{" getvertex()                      " LINK world_getvertex} Get vertex of object
    @{" fastsetvert()                    " LINK world_fastsetvert} Fast add vertex
    @{" delvertex()                      " LINK world_delvertex} Delete vertex from object

    @{" setline()                        " LINK world_setline} Add line to object
    @{" getline()                        " LINK world_getline} Get line from object
    @{" fastsetline()                    " LINK world_fastsetline} Fast add line
    @{" delline()                        " LINK world_delline} Delete line from object

    @{" setsurface()                     " LINK world_setsurface} Add surface to object
    @{" getsurface()                     " LINK world_getsurface} Get surface from object
    @{" delsurface()                     " LINK world_delsurface} Delete surface from object

    @{" visible()                        " LINK world_visible} Switch on and off an object
    @{" position()                       " LINK world_position} Move local axes of an object
    @{" scale()                          " LINK world_scale} Scale an object
    @{" applyobj()                       " LINK world_applyobj} Apply transformations to an object

    @{" projection()                     " LINK world_projection} 3D -> 2D conversion
    @{" getpoint()                       " LINK world_getpoint} Get projected pixel
    @{" draw()                           " LINK world_draw} Draw wireframe (or points)
    @{" init3D()                         " LINK world_init3d} Initialise filled vectors
    @{" drawfill()                       " LINK world_drawfill} Draw filled vectors

    @{" copyobj()                        " LINK world_copyobj} Copy two objects
    @{" cloneobj()                       " LINK world_cloneobj} Duplicate an object

    @{" setobserver()                    " LINK world_setobserver} Position observer
    @{" setscale()                       " LINK world_setscale} Scale all objects
    @{" settrasl()                       " LINK world_settrasl} Traslate all objects
    @{" setrot()                         " LINK world_setrot} Rotate all objects
    @{" setafterscale()                  " LINK world_setafterscale} Scale to fit screen
    @{" setaftertrasl()                  " LINK world_setaftertrasl} Traslate origin of axes
    @{" setdisplay()                     " LINK world_setdisplay} Set display features

    @{" version()                        " LINK world_version} Version of Worldbuilder

@endnode

@node world_o_methods "AFC module: Object_obj methods"

    Object_obj methods:

    COMMANDS                          BRIEF DESCRIPTION
    -----------------------------------------------------------------------

    @{" object_obj()                     " LINK object_obj} Initializes an object
    @{" clear()                          " LINK object_clear} Clear object

    @{" name()                           " LINK object_name} Return object name

    @{" setvertex()                      " LINK object_setvertex} Add vertex
    @{" getvertex()                      " LINK object_getvertex} Get vertex
    @{" fastsetvert()                    " LINK object_fastsetvert} Fast add vertex
    @{" delvertex()                      " LINK object_delvertex} Delete vertex

    @{" setline()                        " LINK object_setline} Add line
    @{" getline()                        " LINK object_getline} Get line
    @{" fastsetline()                    " LINK object_fastsetline} Fast add line
    @{" delline()                        " LINK object_delline} Delete line

    @{" setsurface()                     " LINK object_setsurface} Add surface
    @{" getsurface()                     " LINK object_getsurface} Get surface
    @{" delsurface()                     " LINK object_delsurface} Delete surface

    @{" position()                       " LINK object_position} Move local axes
    @{" scale()                          " LINK object_scale} Scale object
    @{" apply()                          " LINK object_apply} Apply transformations

    @{" projection()                     " LINK object_projection} Project single object
    @{" getpoint()                       " LINK object_getpoint} Get projected pixel

    @{" copy()                           " LINK object_copy} Copy object
    @{" clone()                          " LINK object_clone} Duplicate object

@endnode

@node world_procedures "AFC module: Procedures"

    Procedures:

    COMMANDS                          BRIEF DESCRIPTION
    -----------------------------------------------------------------------

    @{" fillSinTable()                   " LINK world_fillsintable} Initialize table of sines
    @{" limitangle()                     " LINK world_limitangle} Bound angle (0 - 360 degrees)
    @{" crossprod()                      " LINK world_crossprod} Vector product
    @{" dotprod()                        " LINK world_dotprod} Scalar product

@endnode

@node author "Author(s) Info"

    Original By:  Andrea Galimberti

    E Version By: Andrea Galimberti

@endnode

@node world_intro "AFC module: Worldbuilder / Introduction"


   Worldbuilder
   ------------

   This Class contains instructions to create, manipulate and draw three
dimensional objects:  they can be rotated, scaled and drawn in a wireframe
and in a filled vector mode; at any time you can add, remove or modify
vertices, lines and surfaces, the system keeping track automatically of
your changes.


   @{" The objects           " LINK world_i_objects}
   @{" Lines and surfaces    " LINK world_i_lines}
   @{" The coordinate system " LINK world_i_coords}

@endnode

@node world_i_objects "AFC module: Introduction / objects"

   Two are the objects contained in this class:  worldbuilder and object_obj.
The latter represents a single 3D object containing its description in
terms of position of vertices, lines and/or surfaces.  The former
represents the world in which to insert the objects before they are
rendered.  You have to keep in mind this:  objects can be manipulated and
drawn on the screen only when they are in a worldbuilder, because it's the
worldbuilder that contains notions as rotation, traslation, scaling and
observer position.

   The methods are accordingly divided in two sets:  one pertaining to the
worldbuilder and one to the object_obj.  Most of the methods of the two sets
share the same name, because they do exactly the same thing:  the method of
worldbuilder acts on objects already linked to that world, while the
corresponding method of object_obj acts on the single object.
   But why this division can be useful?  I must say that you're invited to
use only the methods of worldbuilder (because otherwise, as I said before,
objects cannot be rendered), but perhaps you may want to keep your own
database of objects and link them to a worldbuilder only when needed, and this
is where the methods of object_obj come into play.

@endnode

@node world_i_lines "AFC module: Introduction / lines and surfaces"

   An object_obj contains vertices, lines and surfaces.  No doubt you have
to define vertices before defining anything else, but you haven't to define
lines before surfaces:  these two structures are independent but, anyway,
they aren't mutually exclusive.  You need lines if you render the world in
wireframe; otherwise, if you use the filled vector mode you need only
surfaces.

@endnode

@node world_i_coords "AFC module: Introduction / coordinate system"

   There's always a weird (for physicists) peculiarity in the coordinate
system of a computer world:  unfortunately it's left-handed.  The three
axes are directed as follows:

              y
               ^   _  z
               |   /|
               |  /
               | /
               |/
               |-----------> x
              0

(obviuosly, negative coordinate values are allowed).

@endnode

@node Error_Table "AFC module: worldbuilder / Error Table"

Val (Hex)  | Description
-----------+------------------------------------------------------
  $0000    | No Memory
  $0001    | AreaInfo not available in init3D()
  $0002    | TempRas not available in init3D()
  $0003    | Vector buffer not available in init3D()
  $0004    | Extra bitplane not available in init3D()

@endnode

@node object_obj "AFC module: object_obj / object_obj()"

          NAME: object_obj(name)

   DESCRIPTION: creates an object_obj with name 'name'.  The name
                parameter is necessary because all objects in a worldbuilder
                are addressed with their names.
                  Objects cannot be rendered independently outside a world;
                the object_obj methods are supplied to manipulate single
                objects e.g. for storing purposes:  you can, for example,
                create a database of objects and then link to an
                initialized worldbuilder only the ones you actually need.
                  To link an already existing object to a worldbuilder you use
                the @{"worldbuilder / setobj()" LINK world_setobj} method; alternatively you can
                directly create and add an object to a world in one step by
                calling the @{"worldbuilder / addobj()" LINK world_addobj} method.

        INPUTS: name of the object to be crated (max 30 chars).

       RESULTS: NONE

      SEE ALSO: @{" worldbuilder / addobj() " LINK world_addobj}
                @{" worldbuilder / setobj() " LINK world_setobj}

@endnode

@node object_clear "AFC module: object_obj / clear()"

          NAME: clear()

   DESCRIPTION: clears all object's contents (except its name).

        INPUTS: NONE

       RESULTS: NONE

      SEE ALSO: @{" worldbuilder / clearobj() " LINK world_clearobj}

@endnode

@node object_setvertex "AFC module: object_obj / setvertex()"

          NAME: setvertex(num, x, y, z)

   DESCRIPTION: if 'num' is greater than the number of vertices of the
                object, then a new vertex is added to the object at the
                last position (independently of its number); so you cannot
                leave holes e.g. by adding vertex 4 and then vertex 10:
                in this case vertex 10 enters in position number 5.

                  This underlines one thing you have to care about:
                vertices have NOT a fixed number; their number it's their
                position in the list (for speed reasons).  Usually the
                module takes care of this automatically, but you must
                remember it when you delete a vertex.

                  If 'num' is an already attached vertex, then this
                instruction modifies the coordinates of that vertex.

                  Vertex numbers start from 0 (just like array elements).

        INPUTS: num: number of the vertex
                x, y, z: coordinates of the vertex.

       RESULTS: FALSE if num<0, otherwise the number of vertices currently
                in object.

      SEE ALSO: @{" fastsetvert()           " LINK object_fastsetvert}
                @{" worldbuilder / setvertex() " LINK world_setvertex}

@endnode

@node object_getvertex "AFC module: object_obj / getvertex()"

          NAME: getvertex(num)

   DESCRIPTION: if num is a valid vertex number (that is to say in the
                range [0 - ((number of vertices of the object)-1)]), this
                call returns a pointer to a vertex_obj.
                  A vertex_obj contains three fields:  x, y and z,
                representing the three coordinates of the vertex.  After
                you got the pointer to a vertex_obj you can access its
                coordinates by the usual way:  vertex_obj.x, vertex_obj.y
                and vertex_obj.z.  I left this structure public because it
                can be of some use for you.

        INPUTS: number of (an existing) vertex; remember: vertex numbers
                start from 0 (and go to (number of vertices in object)-1).

       RESULTS: pointer to a vertex_obj
                FALSE if num is an illegal number (e.g., num<0)

      SEE ALSO: @{" setvertex()             " LINK object_setvertex}
                @{" worldbuilder / getvertex() " LINK world_getvertex}

@endnode

@node object_fastsetvert "AFC module: object_obj / fastsetvert()"

          NAME: fastsetvert(vertex_list)

   DESCRIPTION: adds vertices to the object according to the content of
                vertex_list.  Vertex_list is a TYPED list of type
                vertex_obj with the following form:

                     [x1,y1,z1, x2,y2,z2, ... ]:vertex_obj

                This command is equivalent to the following code

                     FOR k:=0 to (number of vertices)-1
                       o.setvertex(k, x[k], y[k], z[k])
                     ENDFOR

                but it's quicker.

        INPUTS: vertex_list: list of vertices to be added.

       RESULTS: NONE

      SEE ALSO: @{" setvertex()               " LINK object_setvertex}
                @{" worldbuilder / fastsetvert() " LINK world_fastsetvert}

@endnode

@node object_delvertex "AFC module: object_obj / delvertex()"

          NAME: delvertex(num)

   DESCRIPTION: removes a vertex from the object.  Removes all references
                to that vertex by deleting all lines and/or surfaces
                attached to the vertex.
                  All vertex numbers will be scaled down one step to fill
                in the hole leaved by the deletion.

        INPUTS: number of vertex to be killed.

       RESULTS: FALSE if num is not the number of an existing vertex (e.g.,
                num<0), otherwise TRUE.

      SEE ALSO: @{" setvertex()             " LINK object_setvertex}
                @{" worldbuilder / delvertex() " LINK world_delvertex}

@endnode

@node object_setline "AFC module: object_obj / setline()"

          NAME: setline(num, startv, endv, colour)

   DESCRIPTION: adds or modifies line number 'num' in object 'name':  the
                line starts from vertex number 'startv', ends in vertex
                number 'endv' and has colour 'colour'.
                  If num is greater than the number of lines contained in
                the object_obj, then the new line will be added as last
                item; if num points to an existing line, then the new datas
                will replace the old line definition.

                  This underlines one thing you have to care about:
                lines have NOT a fixed number; their number it's their
                position in the list (for speed reasons).  Usually the
                module takes care of this automatically, but you must
                remember it when you delete a line.

                  Line numbers start from 0.

        INPUTS: num: line number,
                startv: starting line vertex,
                endv: ending line vertex,
                colour: line colour.

       RESULTS: FALSE if num<0 or startv and/or endv outside the range of
                  existing vertices of the object,
                otherwise the number of lines currently in object.

      SEE ALSO: @{" worldbuilder / setline() " LINK world_setline}

@endnode

@node object_getline "AFC module: object_obj / getline()"

          NAME: getline(num)

   DESCRIPTION: returns a description of line number 'num' in the form of a
                pointer to a line_obj.  An object of type line_obj contains
                three fields named 'startv', 'endv' and 'colour'; after
                having received the pointer you access those fields in the
                usual way:  line_obj.startv, line_obj.endv and
                line_obj.colour.
                  I left the line_obj object description public because it
                can be of use to you.

        INPUTS: number of line to be inquired.

       RESULTS: FALSE if num is outside the valid range of existing line
                 numbers (going from 0 to (number of lines)-1),
                otherwise a pointer to a line_obj.

      SEE ALSO: @{" setline()             " LINK object_setline}
                @{" worldbuilder / getline() " LINK world_getline}

@endnode

@node object_fastsetline "AFC module: object_obj / fastsetline()"

          NAME: fastsetline(line_list)

   DESCRIPTION: adds the line descriptions contained in line_list to the
                object.  Line_list is a TYPED list of type line_obj of the
                following form:

                [startv1,endv1,colour1, startv2,endv2,colour2, ...]:line_obj

                This command is equivalent to the following code

                     FOR k:=0 to (number of lines)-1
                       o.setline(k, startv[k], endv[k], colour[k])
                     ENDFOR

                but it's quicker.

                If a startv or endv exceeds the range of existing vertex
                numbers for the object, then it is automatically set to
                vertex number 0.

        INPUTS: list of lines to be added.

       RESULTS: NONE

      SEE ALSO: @{" setline()                 " LINK object_setline}
                @{" worldbuilder / fastsetline() " LINK world_fastsetline}

@endnode

@node object_delline "AFC module: object_obj / delline()"

          NAME: delline(num)

   DESCRIPTION: removes line number 'num' from the object.
                  All line numbers will be scaled down one step to fill in
                the hole leaved by the deletion.

        INPUTS: number of line to be killed.

       RESULTS: FALSE if num is outside the valid range for the object.

      SEE ALSO: @{" setline()             " LINK object_setline}
                @{" worldbuilder / delline() " LINK world_delline}

@endnode

@node object_setsurface "AFC module: object_obj / setsurface()"

          NAME: setsurface(num, vertex_list, colour)

   DESCRIPTION: adds (or modifies) a surface.  If num is greater than the
                number of surfaces contained in the object, then the new
                surface will be added at the end of the list; if num points
                to an existing surface, then the contents of that surface
                will be replaced by the new datas.
                  The vertex_list is a list of vertex NUMBERS belonging to
                the surface, in the following order:  you rotate the object
                until the surface is visible and then enumerate the
                vertices in a clockwise direction.

                  I want to underline one thing you have to care about:
                surfaces have NOT a fixed number; their number it's their
                position in the list (for speed reasons).  Usually the
                module takes care of this automatically, but you must
                remember it when you delete a surface.

                  Surface numbers start from 0.

                If a vertex number in the list is outside the range of
                existing vertices, then it is arbitrarily set to vertex
                number 0.

                  If you modify a surface it doesn't matter if the new
                vertex_list is shorter or longer than the previous one.

        INPUTS: num: number of surface,
                vertex_list: list of vertex numbers,
                colour: surface colour register.

       RESULTS: FALSE if num<0,
                otherwise the total number of surfaces in the object.

      SEE ALSO: @{" worldbuilder / setsurface() " LINK world_setsurface}

@endnode

@node object_getsurface "AFC module: object_obj / getsurface()"

          NAME: getsurface(snum, vnum)

   DESCRIPTION: returns the vertex number contained in position vnum of
                surface snum.

        INPUTS: snum: number of surface to be inquired,
                vnum: position of vertex in the surface's list.

       RESULTS: vertex number contained in position vnum,
                FALSE if snum outside the valid range or vnum outside the
                 valid range for the object.

      SEE ALSO: @{" setsurface()             " LINK object_setsurface}
                @{" worldbuilder / getsurface() " LINK world_getsurface}

@endnode

@node object_delsurface "AFC module: object_obj / delsurface()"

          NAME: delsurface(num)

   DESCRIPTION: removes surface number 'num' from the object. All surface
                numbers will be scaled down by one step to fill in the hole
                leaved by the deletion.

        INPUTS: number of the surface to be killed.

       RESULTS: FALSE if num is outside the valid range for the object,
                otherwise TRUE.

      SEE ALSO: @{" setsurface()             " LINK object_setsurface}
                @{" worldbuilder / delsurface() " LINK world_delsurface}

@endnode

@node object_projection "AFC module: object_obj / projection()"

          NAME: projection(x, y, z)

   DESCRIPTION: reduces the 3D coordinates of the object in a 2D
                representation, according to the position of the observer
                (specified with the x, y and z parameters).  Local axes are
                not supplied, so you cannot rotate objects individually;
                besides, you cannot draw objects individually.  To perform
                rotations and drawing you have to link the object to a
                worldbuilder.

        INPUTS: position of the observer.

       RESULTS: NONE

      SEE ALSO: @{" worldbuilder / projection() " LINK world_projection}

@endnode

@node object_getpoint "AFC module: object_obj / getpoint()"

          NAME: getpoint(vertex)

   DESCRIPTION: returns the coordinates of a projected vertex in the form
                of a pointer to a screen_pixel object.  Such an object is
                made of two fields named 'x' and 'y' (guess what they
                mean!); after having got the pointer you access the two
                coordinates by the usual way:  screen_pixel.x,
                screen_pixel.y.

        INPUTS: number of the vertex to be inquired.

       RESULTS: pointer to a screen_pixel object,
                FALSE if vertex is outside the valid range for the object.

      SEE ALSO: @{" projection()           " LINK object_projection}
                @{" worldbuilder / getpoint() " LINK world_getpoint}

@endnode

@node object_position "AFC module: object_obj / position()"

          NAME: position(x, y, z)

   DESCRIPTION: moves the origin of the object's local axes to the
                position specified.  This means you can always enter the
                object's coordinates relative to the object's local origin
                and then move the object around in the worldbuilder.
                  This method only sets the origin coordinates to the new
                values, and the traslation is performed every time the
                object is @{"project()" LINK world_projection}ed within a worldbuilder:  this behaviour
                obviuosly slows down the projection routine.  If you want
                to make the changes permanent (calculated once for ever)
                you call the @{"apply()" LINK object_apply} method.

                  To traslate the whole worldbuilder you can use the
                @{"settrasl()" LINK world_settrasl} method.

        INPUTS: coordinates of the local origin.

       RESULTS: NONE

      SEE ALSO: @{" apply()                " LINK object_apply}
                @{" worldbuilder / position() " LINK world_position}
@endnode

@node object_scale "AFC module: object_obj / scale()"

          NAME: scale(x, y, z)

   DESCRIPTION: scales the object.
                  This method only sets the scaling factors to the new
                values, and the scaling is performed every time the object
                is @{"project()" LINK world_projection}ed within a worldbuilder:  this behaviour
                obviuosly slows down the projection routine.  If you want
                to make the changes permanent (calculated once for ever)
                you call the @{"apply()" LINK object_apply} method.
                  The scaling factors are entered as a percentage:  100
                means original dimensions, 50 means a half, and so on...

                  To scale the whole worldbuilder you can use the
                @{"setscale()" LINK world_setscale} method.

        INPUTS: scaling factors.

       RESULTS: NONE

      SEE ALSO: @{" apply()             " LINK object_apply}
                @{" worldbuilder / scale() " LINK world_scale}

@endnode

@node object_copy "AFC module: object_obj / copy()"

          NAME: copy(dest:PTR TO object_obj)

   DESCRIPTION: copies all the contents of an object (except its name) to
                the destination object:  the latter will be @{"clear()" LINK object_clear}ed
                before being modified.

        INPUTS: pointer to an already initialized object_obj.

       RESULTS: FALSE if dest=NIL, otherwise TRUE.
                It may raise exceptions (see the @{"Error Table" LINK Error_Table}).

      SEE ALSO: @{" clone()               " LINK object_clone}
                @{" worldbuilder / copyobj() " LINK world_copyobj}

@endnode

@node object_clone "AFC module: object_obj / clone()"

          NAME: clone(newname=NIL)

   DESCRIPTION: creates a new object_obj and copies the contents of the
                current object to the new one.  The newname parameter will
                be the name of the newborn object_obj (if it is not
                supplied the new name will be something like
                'Copy_of_oldname').

        INPUTS: name of the object to be created.

       RESULTS: pointer to the new object_obj.

      SEE ALSO: @{" copy()                 " LINK object_copy}
                @{" worldbuilder / cloneobj() " LINK world_cloneobj}

@endnode

@node object_name "AFC module: object_obj / name()"

          NAME: name()

   DESCRIPTION: returns the object's name.

        INPUTS: NONE

       RESULTS: object's name.

      SEE ALSO:

@endnode

@node object_apply "AFC module: object_obj / apply()"

          NAME: apply()

   DESCRIPTION: makes the changes on an object permanent (calculated once
                for ever).  Changes such as @{"position()" LINK object_position} or @{"scale()" LINK object_scale} of an
                object_obj are affected:  this increases the speed of the
                @{"projection()" LINK world_projection} routine, because permanent transformations
                are skipped.

        INPUTS: NONE

       RESULTS: NONE

      SEE ALSO: @{" position()             " LINK object_position}
                @{" scale()                " LINK object_scale}
                @{" worldbuilder / applyobj() " LINK world_applyobj}

@endnode

@node worldbuilder "AFC module: worldbuilder / worldbuilder()"

          NAME: worldbuilder()

   DESCRIPTION: builds a worldbuilder object (constructor).

        INPUTS: NONE

       RESULTS: NONE

      SEE ALSO:

@endnode

@node world_addobj "AFC module: worldbuilder / addobj()"

          NAME: addobj(name)

   DESCRIPTION: creates an object_obj called 'name' and adds it to the
                worldbuilder.  The name parameter is necessary because all
                objects in a world are recognized by their names.

        INPUTS: the name of the object to be created (max 30 chars).

       RESULTS: NONE

      SEE ALSO: @{" object_obj() " LINK object_obj}
                @{" setobj()     " LINK world_setobj}

@endnode

@node world_setobj "AFC module: worldbuilder / setobj()"

          NAME: setobj(object)

   DESCRIPTION: links an existing object_obj to the worldbuilder.

        INPUTS: 'object' is the pointer to an object_obj.

       RESULTS: NONE

      SEE ALSO: @{" addobj() " LINK world_addobj}
                @{" getobj() " LINK world_getobj}

@endnode

@node world_getobj "AFC module: worldbuilder / getobj()"

          NAME: getobj(name)

   DESCRIPTION: returns the pointer to the object_obj named 'name'.

        INPUTS: name of the object.

       RESULTS: pointer to an object_obj.

      SEE ALSO: @{" setobj() " LINK world_setobj}
                @{" addobj() " LINK world_addobj}

@endnode

@node world_delobj "AFC module: worldbuilder / delobj()"

          NAME: delobj(name)

   DESCRIPTION: unlinks from the worldbuilder and deletes (freeing all memory
                associated with it) the object 'name'.  If such an object
                doesn't exist, it does nothing.

        INPUTS: name of the object to be killed.

       RESULTS: NONE

      SEE ALSO: @{" addobj()    " LINK world_addobj}
                @{" unlinkobj() " LINK world_unlinkobj}

@endnode

@node world_unlinkobj "AFC module: worldbuilder / unlinkobj()"

          NAME: unlinkobj(name)

   DESCRIPTION: removes the object 'name' from the worldbuilder, without
                freeing its memory.  It returns a pointer to an object_obj,
                that you must remember to END yourself before exiting the
                program.

        INPUTS: name of the object to unlink.

       RESULTS: pointer to an object_obj, or FALSE if 'name' not found.

      SEE ALSO: @{" delobj() " LINK world_delobj}

@endnode

@node world_setvertex "AFC module: worldbuilder / setvertex()"

          NAME: setvertex(name, num, x, y, z)

   DESCRIPTION: same as @{"object_obj / setvertex()" LINK object_setvertex}

        INPUTS: name of the object_obj to be modified
                num: vertex number
                x, y, z: vertex coordinates

       RESULTS: FALSE if object not found,
                otherwise the number of vertices currently in object.

      SEE ALSO: @{" fastsetvert()            " LINK world_fastsetvert}
                @{" object_obj / setvertex() " LINK object_setvertex}

@endnode

@node world_getvertex "AFC module: worldbuilder / getvertex()"

          NAME: getvertex(name, num)

   DESCRIPTION: same as @{"object_obj / getvertex()" LINK object_getvertex}

        INPUTS: name of the object to be inquired
                num: number of vertex

       RESULTS: FALSE if object not found, or num outside a valid range,
                pointer to vertex_obj if successful.

      SEE ALSO: @{" setvertex()              " LINK world_setvertex}
                @{" object_obj / getvertex() " LINK object_getvertex}

@endnode

@node world_fastsetvert "AFC module: worldbuilder / fastsetvert()"

          NAME: fastsetvert(name, vertex_list)

   DESCRIPTION: same as @{"object_obj / fastsetvert()" LINK object_fastsetvert}

        INPUTS: name of the object to be modified
                vertex_list of vertices to be added.

       RESULTS: FALSE if object not found.

      SEE ALSO: @{" setvertex()                " LINK world_setvertex}
                @{" object_obj / fastsetvert() " LINK object_fastsetvert}

@endnode

@node world_delvertex "AFC module: worldbuilder / delvertex()"

          NAME: delvertex(name, num)

   DESCRIPTION: same as @{"object_obj / delvertex()" LINK object_delvertex}

        INPUTS: name of the object to be modified
                num: number of vertex to be killed.

       RESULTS: FALSE if object not found, or num outside a valid range,
                otherwise TRUE.

      SEE ALSO: @{" setvertex()              " LINK world_setvertex}
                @{" object_obj / delvertex() " LINK object_delvertex}

@endnode

@node world_setline "AFC module: worldbuilder / setline()"

          NAME: setline(name, num, startv, endv, colour)

   DESCRIPTION: same as @{"object_obj / setline()" LINK object_setline}

        INPUTS: name of the object to be modified,
                num: number of line,
                startv: line starting vertex,
                endv: line ending vertex,
                colour: line colour register.

       RESULTS: FALSE if object not found,
                FALSE if num<0 or startv and/or endv outside the range of
                  existing vertices of the object,
                otherwise the number of lines currently in the object.

      SEE ALSO: @{" fastsetline()          " LINK world_fastsetline}
                @{" object_obj / setline() " LINK object_setline}

@endnode

@node world_getline "AFC module: worldbuilder / getline()"

          NAME: getline(name, num)

   DESCRIPTION: same as @{"object_obj / getline()" LINK object_getline}

        INPUTS: name of the object,
                num: line number.

       RESULTS: FALSE if object not found, or num outside the range of
                existing line numbers.

      SEE ALSO: @{" setline()              " LINK world_setline}
                @{" object_obj / getline() " LINK object_getline}

@endnode

@node world_fastsetline "AFC module: worldbuilder / fastsetline()"

          NAME: fastsetline(name, line_list)

   DESCRIPTION: same as @{"object_obj / fastsetline()" LINK object_fastsetline}

        INPUTS: name of the object to be modified,
                line_list: typed list of objects line_obj.

       RESULTS: FALSE if object not found, otherwise TRUE

      SEE ALSO: @{" setline()                  " LINK world_setline}
                @{" object_obj / fastsetline() " LINK object_fastsetline}

@endnode

@node world_delline "AFC module: worldbuilder / delline()"

          NAME: delline(name, num)

   DESCRIPTION: same as @{"object_obj / delline()" LINK object_delline}

        INPUTS: name of the object to be modified,
                num: number of line to be killed.

       RESULTS: FALSE if object not found, or num outside the valid line
                numbers range for the object.

      SEE ALSO: @{" setline()              " LINK world_setline}
                @{" object_obj / delline() " LINK object_delline}

@endnode

@node world_setsurface "AFC module: worldbuilder / setsurface()"

          NAME: setsurface(name, num, vertex_list, colour)

   DESCRIPTION: same as @{"object_obj / setsurface()" LINK object_setsurface}

        INPUTS: name of the object to be modified,
                num: number of surface,
                vertex_list: list of vertex numbers defining the surface,
                colour: surface colour register.

       RESULTS: FALSE if object not found, or num<0

      SEE ALSO: @{" object_obj / setsurface() " LINK object_setsurface}

@endnode

@node world_getsurface "AFC module: worldbuilder / getsurface()"

          NAME: getsurface(name, snum, vnum)

   DESCRIPTION: same as @{"object_obj / getsurface()" LINK object_getsurface}

        INPUTS: name of the object,
                snum: number of surface to be inquired,
                vnum: number of vertex

       RESULTS: FALSE if object not found or snum outside the valid range
                 or vnum outside the valid range for the object,
                otherwise the vertex number in position vnum.

      SEE ALSO: @{" setsurface()              " LINK world_setsurface}
                @{" object_obj / getsurface() " LINK object_getsurface}

@endnode

@node world_delsurface "AFC module: worldbuilder / delsurface()"

          NAME: delsurface(name, num)

   DESCRIPTION: same as @{"object_obj / delsurface()" LINK object_delsurface}

        INPUTS: name of the object to be modified,
                num: number of surface to be killed.

       RESULTS: FALSE if object not found or num outside the valid surface
                 number range for the object,
                otherwise TRUE.

      SEE ALSO: @{" setsurface()              " LINK world_setsurface}
                @{" object_obj / delsurface() " LINK object_delsurface}

@endnode

@node world_getpoint "AFC module: worldbuilder / getpoint()"

          NAME: getpoint(name, vertex)

   DESCRIPTION: same as @{"object_obj / getpoint()" LINK object_getpoint}

        INPUTS: name of the object,
                vertex number to be inquired.

       RESULTS: FALSE if object not found or vertex number outside the
                 valid range for the object,
                otherwise the pointer to a screen_pixel object.

      SEE ALSO: @{" object_obj / getpoint() " LINK object_getpoint}

@endnode

@node world_visible "AFC module: worldbuilder / visible()"

          NAME: visible(name [,v])

   DESCRIPTION: an object is by default visible, that is to say it will be
                drawn on the scene.  If v=FALSE then the object won't
                appear on the scene any more, until v is reset to TRUE.  If
                v is omitted then the function returns the state of the
                object.

        INPUTS: name of the object to be modified,
                v: TRUE if visible, FALSE if not

       RESULTS: FALSE if object not found, otherwise TRUE; if v is omitted
                then the result is the state of the object.

      SEE ALSO:

@endnode

@node world_position "AFC module: worldbuilder / position()"

          NAME: position(name, x,y,z)

   DESCRIPTION: same as @{"object_obj / position()" LINK object_position}.

        INPUTS: name of the object ot be modified,
                coordinates of the local origin.

       RESULTS: FALSE if object not found.

      SEE ALSO: @{" applyobj()              " LINK world_applyobj}
                @{" object_obj / position() " LINK object_position}

@endnode

@node world_scale "AFC module: worldbuilder / scale()"

          NAME: scale(name, x,y,z)

   DESCRIPTION: same as @{"object_obj / scale()" LINK object_scale}.

        INPUTS: name of the object to be modified,
                scaling factors.

       RESULTS: FALSE if object not found.

      SEE ALSO: @{" applyobj()           " LINK world_applyobj}
                @{" object_obj / scale() " LINK object_scale}

@endnode

@node world_clearobj "AFC module: worldbuilder / clearobj()"

          NAME: clearobj(name)

   DESCRIPTION: same as @{"object_obj / clear()" LINK object_clear}.

        INPUTS: name of the object to be cleared.

       RESULTS: FALSE if object not found, otherwise TRUE.

      SEE ALSO: @{" object_obj / clear() " LINK object_clear}

@endnode

@node world_copyobj "AFC module: worldbuilder / copyobj()"

          NAME: copyobj(source_name, dest_name)

   DESCRIPTION: copies the contents of source_name object to dest_name
                object (except names).

        INPUTS: name of two object_obj's.

       RESULTS: FALSE if either of the objects has not been found.

      SEE ALSO: @{" cloneobj()          " LINK world_cloneobj}
                @{" object_obj / copy() " LINK object_copy}

@endnode

@node world_cloneobj "AFC module: worldbuilder / cloneobj()"

          NAME: cloneobj(name, new_name=NIL)

   DESCRIPTION: creates a new object of name new_name (if supplied),
                copies the contents of the object_obj 'name' in the newborn
                object, and then links the latter to the worldbuilder.

        INPUTS: name of the object to be cloned,
                new_name:  name of the new object (if not supplied the
                 default is 'Copy_of_name').

       RESULTS: FALSE if object 'name' not found.

      SEE ALSO: @{" copyobj()            " LINK world_copyobj}
                @{" object_obj / clone() " LINK object_clone}

@endnode

@node world_applyobj "AFC module: worldbuilder / applyobj()"

          NAME: applyobj(name)

   DESCRIPTION: same as @{"object_obj / apply()" LINK object_apply}.

        INPUTS: name of the object to be modified.

       RESULTS: FALSE if object not found.

      SEE ALSO: @{" position()           " LINK world_position}
                @{" scale()              " LINK world_scale}
                @{" object_obj / apply() " LINK object_apply}

@endnode

@node world_projection "AFC module: worldbuilder / projection()"

          NAME: projection()

   DESCRIPTION: transforms the 3D representation of the world in a 2D
                representation, according with the chosen values of
                rotantion angles (@{"setrot()" LINK world_setrot} method) and observer position
                (@{"setobserver()" LINK world_setobserver} method).
                  You have to call this instruction before the drawing
                routine, if you have performed some changes on the
                worldbuilder.

        INPUTS: NONE

       RESULTS: NONE

      SEE ALSO: @{" object_obj / projection() " LINK object_projection}

@endnode

@node world_draw "AFC module: worldbuilder / draw()"

          NAME: draw(rastport)

   DESCRIPTION: draws the worldbuilder in a wireframe fashion.  If an object
                has at least one line, then only its lines are drawn; if an
                object has no lines, then its vertices are drawn.  Rastport
                is the address of a valid rastport in which to draw the
                graphics.
                  The drawing is then traslated and scaled according to the
                values entered with the @{"setaftertrasl()" LINK world_setaftertrasl} and
                @{"setafterscale()" LINK world_setafterscale} methods.
                  Remember to @{"projection()" LINK world_projection} the worldbuilder before drawing
                it (you needn't do this if it's not the first time and
                you've made no changes).

        INPUTS: address of a rastport.

       RESULTS: NONE

      SEE ALSO: @{" drawfill()   " LINK world_drawfill}
                @{" projection() " LINK world_projection}

@endnode

@node world_drawfill "AFC module: worldbuilder / drawfill()"

          NAME: drawfill(rastport, onlylines=FALSE)

   DESCRIPTION: draws the projected worldbuilder with filled vectors.
                  The drawing is then traslated and scaled according to the
                values entered with the @{"setaftertrasl()" LINK world_setaftertrasl} and
                @{"setafterscale()" LINK world_setafterscale} methods.
                  Clipping is made according to the dimensions of the
                screen area entered with the @{"setdisplay()" LINK world_setdisplay} method.
                  If the onlylines parameter is set to TRUE, then also
                objects without surfaces are drawn.
                  
                  Remember to @{"projection()" LINK world_projection} the worldbuilder before drawing
                it (you needn't do this if it's not the first time and
                you've made no changes).
                  You must call the @{"init3D()" LINK world_init3d} routine at least one time
                before drawing any filled graphics.

        INPUTS: address of a rastport in which to draw the graphics.

       RESULTS: NONE

      SEE ALSO: Important: @{" init3D() " LINK world_init3d}
                @{" projection() " LINK world_projection}

@endnode

@node world_setobserver "AFC module: worldbuilder / setobserver()"

          NAME: setobserver(x, y, z)

   DESCRIPTION: sets the observer position.

        INPUTS: coordinates of the observer.

       RESULTS: NONE

      SEE ALSO:

@endnode

@node world_setscale "AFC module: worldbuilder / setscale()"

          NAME: setscale(x, y, z)

   DESCRIPTION: the three scale factors will be applied to the whole
                worldbuilder before projecting it.  They are entered as a
                percentage:  100 means original dimensions, 50 means a
                half, and so on...
                  This is a 3D operation:  compare it with
                @{"setafterscale()" LINK world_setafterscale}

        INPUTS: scaling factors in the three directions.

       RESULTS: NONE

      SEE ALSO: @{" setafterscale() " LINK world_setafterscale}

@endnode

@node world_settrasl "AFC module: worldbuilder / settrasl()"

          NAME: settrasl(tx, ty, tz)

   DESCRIPTION: traslates the whole worldbuilder by the specified amounts
                before projecting it.
                  This is a 3D operation:  compare it with
                @{"setaftertrasl()" LINK world_setaftertrasl}

                The traslation is done before any rotation is performed.

        INPUTS: traslation amounts in the three directions.

       RESULTS: NONE

      SEE ALSO: @{" setaftertrasl() " LINK world_setaftertrasl}

@endnode

@node world_setrot "AFC module: worldbuilder / setrot()"

          NAME: setrot(x, y, z)

   DESCRIPTION: rotates the whole worldbuilder around the three axes by the
                specified amounts.

        INPUTS: angles of rotation around the three axes (degrees).

       RESULTS: NONE

      SEE ALSO:

@endnode

@node world_setafterscale "AFC module: worldbuilder / setafterscale()"

          NAME: setafterscale(x, y)

   DESCRIPTION: scales the projected world while drawing it to adapt it to
                the screen area.  The scaling factors are entered as a
                percentage:  100 means original dimensions, 50 means a
                half, and so on...
                  This is a 2D operation:  compare it with @{"setscale()" LINK world_setscale}

        INPUTS: scaling factors in the two directions.

       RESULTS: NONE

      SEE ALSO: @{" setscale() " LINK world_setscale}

@endnode

@node world_setaftertrasl "AFC module: worldbuilder / setaftertrasl()"

          NAME: setaftertrasl(x, y)

   DESCRIPTION: translates the origin of the screen coordinate system
                (default: top left-hand corner, as usual).
                  This is a 2D operation:  compare it with @{"settrasl()" LINK world_settrasl}

        INPUTS: traslation factors in the two directions.

       RESULTS: NONE

      SEE ALSO: @{" settrasl() " LINK world_settrasl}

@endnode

@node world_setdisplay "AFC module: worldbuilder / setdisplay()"

          NAME: setdisplay(width, height)

   DESCRIPTION: used to enter the screen area dimensions.  These are used
                in the allocation of the extra bitplane in the @{"init3D()" LINK world_init3d}
                routine, and in the clipping of graphics in the
                @{"drawfill()" LINK world_drawfill} method.

        INPUTS: width and height of the drawing area (defaults are:
                width=320, height=256).

       RESULTS: NONE

      SEE ALSO:

@endnode

@node world_init3d "AFC module: worldbuilder / init3D()"

          NAME: init3D(bufon=TRUE, dispon=TRUE)

   DESCRIPTION: allocates the resources needed by the @{"drawfill()" LINK world_drawfill} method
                to draw filled vectors:  you must call this routine before
                any call to drawfill() is made.
                   It allocates a buffer needed by the operating system to
                store the vectors before they are drawn, and an extra
                bitplane to allow the drawing of filled areas.  If, in a
                second time, you change the dimensions of the screen area,
                you have to recall this routine to update the dimensions of
                the extra bitplane; in the same manner, if you add lots of
                surfaces to your world, you have to call this routine to
                adapt the buffer dimensions to the new situation (otherwise
                you can get only partial rendering).
                   You needn't do both the operations every time you call
                the init3D method, infact the two flags mean:

                        bufon =TRUE  ->  resize the buffer
                        dispon=TRUE  ->  resize the extra bitplane.

                   The dimensions of the screen area are entered with the
                @{"setdisplay()" LINK world_setdisplay} method, and they are used also for graphic
                clipping purposes.

        INPUTS: flags described above.

       RESULTS: raises some exceptions if memory allocation fails (see the
                @{"Error Table" LINK Error_Table}).

      SEE ALSO: @{" drawfill() " LINK world_drawfill}

@endnode

@node world_version "AFC module: worldbuilder / version()"

          NAME: version()

   DESCRIPTION: returns version and revision of worldbuilder module

        INPUTS: NONE

       RESULTS: version, revision

      SEE ALSO:

@endnode

@node world_limitangle "AFC module: procedure / limitangle()"

          NAME: limitangle(angle)

   DESCRIPTION: bounds the angle in range [0-359] degrees.

        INPUTS: angle to be wrapped.

       RESULTS: angle in the range [0-359] degrees

      SEE ALSO:

@endnode

@node world_crossprod "AFC module: procedure / crossprod()"

          NAME: crossprod(a:PTR TO vertex_obj, b:PTR TO vertex_obj)

   DESCRIPTION: this is the vector product between the two vectors 'a' and
                'b'.  The two arguments are defined as vertex_obj because
                points in three-space and three-dimensional vectors share
                the same structure (remember:  points can be represented as
                vectors from the origin).
                  The vectors have three fields:  a.x, a.y and a.z; you
                fill in these fields and call the routine:  it returns the
                three components of the resulting vector.

        INPUTS: two (pointers to) vectors.

       RESULTS: three return values, representing the three components of
                the resulting vector, in the order:  x, y, z.

      SEE ALSO: @{" dotprod() " LINK world_dotprod}

@endnode

@node world_dotprod "AFC module: procedure / dotprod()"

          NAME: dotprod(a:PTR TO vertex_obj, b:PTR TO vertex_obj)

   DESCRIPTION:  this is the scalar product between the two vectors 'a' and
                 'b'.  See the observations about points and vectors in the
                 @{"crossprod()" LINK world_crossprod} procedure.

        INPUTS: two (pointers to) vectors.

       RESULTS: scalar product of the two vectors.

      SEE ALSO: @{" crossprod() " LINK world_crossprod}

@endnode

@node world_fillsintable "AFC module: procedure / fillSinTable()"

          NAME: fillSinTable()

   DESCRIPTION: this is used to fill in a pointer to the table of sines:
                of course, sines for rotations are not calculated realtime,
                but peeked from this table.  The table is automatically
                filled when you create the first worldbuilder object, so, in
                general, you have not to do this task by hand.  On the
                other hand, if you don't fill the table before accessing it
                you can crash your machine.

        INPUTS: NONE

       RESULTS: NONE

      SEE ALSO:

@endnode

