Jongl specification: old objects

Date of issue of this Guide: 16-mar-2002

Old Object files

These objects files are called "old" because since V8.0 Jongl supports VRML objects as well. And starting with V9.0 Jongl does not understand the old object syntax (VRML objects are nicer and faster). Old object files are found in the subdirectory 'o' of the current directory. These are the objects which may be thrown around. There is also another subdirectory called 'o/basic' which defines the static objects. Objects may be built out of the following topics.
                  Points 
                   Lines 
               Triangles 
                Polygons 
                 Spheres 
                   Flags 
                Rotation 
                  Colour 
         Object comments 

Beispiel: o/KeuleLight (Keule = club)

.....................

 r=1

 *

 8 POINTS

 0    0     -.35     #0

 0    0     -.06     #1

 -.06 -.052  .1
  .06 -.052  .1      #2-4
 0     .104  .1

 -.03 -.026  .25
  .03 -.026  .25     #5-7
 0     .052  .25

 10 LINES

 (7 0)   0 1
 (4 0)   1 2
 (4 0)   2 5
 (4 0)   1 3
 (4 0)   3 6
 (4 0)   1 4
 (4 0)   4 7
 (4 0)   5 7
 (4 0)   7 6
 (4 0)   6 5

The club is defined in a vertical attitude with the handle in the 
-Z direction.

....................

The file is divided into two logical blocks. The first one is optional
and may contain one ore more of the following parameters:


h=...   This is the number of points per hand. This value has to be
        defined for a juggler. Otherwise it must not appear. 

k=...   The same, but for the number of points of the head.


r=...   This parameter is of interest only for objects flying around, as
        it defines the Rotation. r=0 means that the object does rotate
        at all (like the potted plant), r=1 means that the object rotates
        like a club.

The dividing character between the two blocks is a *.

Next are at least two of the following sections:

POINTs
LINEs
TRIANGLEs
POLYGONs
SPHEREs
Sections which are not relevant need not be listed. Also the plural for single object parts is not required. That means you may write as well "3 TRIANGLE".

The round brackets within the definitions must not be left out. Their purpose is to aid in the orientation within the program in future versions. (Sounds good, doesn't it?)


Points

POINTS are entered in 3D coordinates in the usual sequence x,y,z. Of course we are working with a right hand coordinate system which means X to the right, Y forward (into the screen) and Z upward.

If you want to see the axes you can select a floor with axes by entering "FLOOR 1" before starting JONGL.

All values are given in units of METRES. (Again for you non-Europeans, one metre is equal to 3.2808398 feet.) Objects which fly like clubs have to be aligned with their handle in the -Z direction. The program rotates them by 90° so that the hand holds them horizontally.
In the following, we refer back to the points. Therefore you have to know that numbering starts with 0. So 13 points run from 0 to 12.

Now we come to Lines.

Lines

As the next step LINES are defined. Each line is defined by its Colour and its Flags. As a consequence, each line can have a different colour. Colour and flags are put in brackets. This will ensure that the files do not have to be changed if the object format is to be expanded later-on.
Starting and end points of lines: In the example above, the first line has the colour 7 and extends between points no. 0 and 1. The next line starts at no. 1 and ends at no. 2; it has the colour 4.

(7 0) 0 1
(4 0) 1 2
Both lines have the flag value 0, that means no bit is set. In other words, currently there are no sensible flags for lines or spheres anyway.

We come to Triangles.

Triangles

TRIANGLES are defined as follows: Colour on the front side (see under Flags), Colour on the rear side, Flags. Finally the three corner points of the triangle.

Example:

(1 2 3) 5 6 7
This triangle has colour 1 on the front side and colour 2 on the rear side. The flags are showing 3. So the bits 0 and 2 are set. The triangle is therefore filled-in and visible from both sides.
The three points of the triangle are 5, 6 and 7.

Now let's look at Polygons.

Polygons

Also for POLYGONS we have first the three parameters "front side Colour" "rear side colour" and Flags, which have been explained already under TRIANGLES.

New with V4.6 is the optional fourth parameter, meaning the number of attached polygons. Those are displayed when the chief polygon is visible. That's the way to define the star on the back of the punk. The attached polygons have to be directly behind the chief polygon.
Next come the corner points of the polygon. Please note that the first point has to be put in again as the last point.

1st example:
(4 5 2)   11 6 7 8 9 11    (Colours 4 & 5; Flag 2; both sides wire frame,
                           the polygon has 5 corners.)
An important restriction for a correct presentation is that only convex polygons can be used. In other words, there cannot be any corners looking inward. Also the polygon has to be in one plane.

Funny effects can be achieved by defining polygons with holes. For this purpose a minus sign (-) and the point numbers are added to the normal definition.


2nd example:

(4 5 3) 11 6 7 8 9 11 - 21 16 17 21
We see that the hole may have a different number of points, but it does not have to. However the hole has to have the same sense of rotation as the polygon!


3rd example:

(4 5 3 4) 1 2 3 4 1     ! this is the chief followed by 4 attached polygons
  (6 6 1) 55 55         ! this is a point
  (1 1 0) 31 33 31      ! this is a line
  (4 3 1) 45 46 47 45   ! this is a triangle
  (15 6 3) 11 12 13 14 15 16 11   ! at last: a polygon
If you have understood everything up to now, you are cleared to get into Spheres.

Spheres

A SPHERE is defined by four parameters: Colour, Flags, point number, radius.

Example:

(4 0) 17 0.06    (Colour 4, flags=0, point number 17, radius 0.06 m)
For the colour we have a special feature: As a return for -1 we get a colour chosen at random. (See also in the object file 'o/ball_random'.)
The point number is the number of the Points which defines the centre of the sphere.
The only flag is bit 4 = 1 which switches off the light reflections. See the use of this in the object "o/basic/Charlie".

Flags

FLAGS are defined as follows:
  bit 0 = 0: wire frame
  bit 0 = 1: filled-in polygons

  bit 1 = 0: only frontside visible (see above)
  bit 1 = 1: both sides visible (but maybe with different colours)

  bit 4 = 1: draw spheres without highlight (see also above)

  For triangles and polygons, the colour  is determined  by  the  sense  of
  rotation of the corner points:
     clockwise     - front side
     anticlockwise - rear side

            

Rotation

ROTATION of the object can assume the following values:

  0: it does not rotate
  1: it rotates 
(-1: it is human: it bends its head and moves its arms)
People - or, more generally speaking, objects (or should I say subjects?) - who/which throw other objects around MUST be built according to the following sequence, because this is the basis for the calculation of hand and head motions.

The first 'h=...' points are the left hand. The next 'h=...' points are the right hand.
Next are the 'k=...' points which define the head. ('h=' und 'k=' are explained in Object files.)

The first two points of the head define the axis of rotation. If the juggler bends his head forward, then these two points have to be exchanged.

Colour

The program uses 16 colours in standard mode. The colour palettes in the other modes differ more or less.

Colour 0is the background which is more or less black most of the time.
Colour 1 yellow
Colour 2 beige (skin colour)
Colour 3 dark green
Colour 4 light red
Colour 5 pink
Colour 6 light blue
Colour 7 light grey
Colour 8 visible black (black in front of a colour, otherwise grey)
Colour 9 orange
Colour 10 brown
Colour 11 light green
Colour 12 dark red
Colour 13 purple
Colour 14 dark blue
Colour 15 dark grey

Colours 0...7 cannot be changed. Colours 8 to 31 change according to the mode currently active.

You may type in negative numbers for colors. -1 denotes the 1st random color in this object. -2 is the 2nd (probably different) random color. This way you can have more than one side of an object colored with the same random color. See o/club_random.


Object comments

COMMENTS in object files may presently be inserted in three places:

a) in the first part (before the *), if the comment starts with an !,
   like in the pattern file which I am going to explain in a minute,

b) behind the 3D coordinates until the end of line,

c) behind the last line of the object, and there is no limit...

See the complete specification.

The end. Check www.jongl.de for new versions.
Please send your thoughts, bug reports and money orders to w e r n e r   a t   j o n g l   d o t   d e.