WF-3D Viewer Object Interface
You can link WF-3D to your own programs so that you can call WF-3D commands/operations directly,
without using a socket or file interface.
To use the WF-3D object interface (API):
- Include wf3d.h in your application (by #include "wf3d.h").
- Call WF_Init (once) to bring up the WF3D window.
- Have your application call WF_FrameUpdate periodically/iteratively.
(You may need to call this more often than you do other things in your application.
This updates the screen, and smooth motion requires many frames per second.)
- Add the wf3d.o file to your link command.
For example, consider the simple application file your_app.c:
#include <stdio.h>
#include "wf3d.h" /* Include the WF3D headers. */
main( int argc, char **argv )
{
/* --- Your application initialization code can go here. --- */
WF_Init( argc, argv ); /* Initialize and open the WF3D window. */
while (1)
{
/* --- Your application code can go here. --- */
WF_FrameUpdate(); /* Display updated frame. */
}
}
Compile on Linux with:
cc -L/usr/X11R6/lib your_app.c wf3d.o -lpthread -lGLU -lGL -lXmu -lXext \
-lX11 -lm -lpthread -o your_app.exe
Compile on MS-windows with:
cc your_app.c wf3d.o -lglu32 -lopengl32 -lwinmm -lgdi32 -o your_app.exe
The following sections describe the balance of the function calls.
The camera setup must be done first, before anything else.
void WF3D_Set_Camera( float fov, float minZ, float maxZ,
float x, float y, float z,
float pointx, float pointy, float pointz );
Example:
WF3D_Set_Camera( 45.0, 2.5, 12000.0, 0.0, 1200.0, -4900.0, 0.0, 0.0, -2350.0 );
Where: fov is View_angle in degrees. (Frustum is the viewable volume in front of the
virtual camera, or viewing location.)
minZ is near-field, the closest range from the camera that objects will be visible.
maxZ is far-field, the farthest range.
Convention is to assume coordinates are in meters.
X-axis is initially left-right (for camera position x=0 with z=negative).
Y-axis is up-down (positive y is up).
Z-axis is into screen.
The pointx ... values specify where the camera is pointing at.
Camera settings can be changed throughout simulation.
If unsure about these settings, experiment. Frustum can also be varied
interactively under the Meta-menu.
void WF3D_Define_Object_Begin( char *type_name ); /* Required. */
void WF3D_Set_Color( float r, float g, float b, float t ); /* As needed */
void WF3D_Add_Triangle( int sides, vx1, vy1, vz1, /* As needed */
vx2, vy2, vz2, vx3, vy3, vz3 );
void WF3D_Add_Quad( int sides, vx1, vy1, vz1, /* As needed. */
vx2, vy2, vz2, vx3, vy3, vz3,
vx4, vy4, vz4 );
void WF3D_Define_Object_End(); /* Required. */
In WF3D_Set_Color() can be called anywhere between the Begin/End to set or change drawing colors.
Color r,g,b and t, where t is transparency (1=solid, 0=clear, 0.5=translucent, etc.).
Sides can be 1 or 2. All vertices are floating-point.
Objects can be defined with triangular polygons and/or quadrilateral polygons (Quads).
Object definitions must start with a call to WF3D_Define_Object_Begin(name), and end with
WF3D_Define_Object_End(). In between are calls to define the polygons.
Note there are four vertices per a quad. Special care must be taken, when using quads,
to not cross the vertices, like an hour-class shape. Open GL does not support that.
A key point to note is that, by default, triangles and quadrilaterals are visible only from their
front side. (This is advantageous because it is more efficient as most objects are viewed from
one side. For example the walls of any solid object, such as a boat or a building, as viewed from outside.)
The front side is determined
by the pointing direction of the vector norm of the vertices, - also called the winding.
If you get the winding (order of the vertices)
wrong, you may notice your triangle is viewable from the wrong side. Simply reverse the
winding by flipping a pair of vertices in the case of a triangle, or by re-ordering three vertices
of a quad.
A simple way to avoid the wrong-side problem is to use two-sided polygons. These are also
useful when you are describing a thin surface which actually can be viewed from both sides.
Scaling and Offsets:
void WF3D_Change_Object_Scale( float SC );
void WF3D_Change_Object_Offset( float XX, float YY, float ZZ );
Where SC is the scale amount, and XX, YY, ZZ are the offset amounts for x
y, and z axes, respectively. These commands scale or offset all subsequent
objects by the designated amounts. This can be used to fit objects
which were defined with greatly differing sizes into common scenes.
Also allows changing the centers for better rotations.
The above change the scale and offset states while defining a given object.
The following calls set the default scale and offset for all future objects unless changed.
void WF3D_Set_Object_Scale( float SC );
void WF3D_Set_Object_Offset( float XX, float YY, float ZZ );
void WF3D_Instantiate_Object( char *instance_name, char *type_name,
float x, float y, float z,
float xAxisAngle, float yAxisAngle, float zAxisAngle
);
Where x,y,z is initial position, and the remaining are the initial angles in degrees.
The above is useful for instantiating the initial objects. To add new objects at
later times, use:
void WF3D_Instantiate_Object_At( char *instance_name, char *type_name, float T
float x, float y, float z,
float xAxisAngle, float yAxisAngle, float zAxisAngle
);
Where T is instantiation time.
Example
WF3D_Instantiate_Object( "Building_37", "BuildingTypeA", 0, 0, 0, 0, 0, 0 );
Instance Scaling - WF3D_Set_Object_Scale( float SC );
- Affects the instantiation positions.
- Is obeyed when encountered anywhere between objects.
(Except within an object's definition where it is local.)
- Remains set to whatever, until re-set back to 1.0.
- Does not affect an instance of an object's defined size,
but does scale the position values of the instantiated object.
moveobject
void WF3D_Move_Object( char *instance_name, int relT, float T1, float T2,
float x, float y, float z );
rotateobject
void WF3D_Rotate_Object( char *instance_name, int relT, float T1, float T2,
float xang, float yang, float zang )
orbitobject
void WF3D_Orbit_Object( char *instance_name, int relT, float T1, float T2,
float x, float y, float z, char axis, float yang )
The relT, or relative flag, when true, instructs the
viewer to move the object for the duration specified, beginning whenever the command
is received by the viewer. This permits non-synchronized/real-time simulations to
drive the viewer. This is time-relative, or relative to the current time.
When false, the T1 and T2 are taken as the absolute times to start and stop the movement
respectively.
All angles are specified in degrees.
The axis parameter in the orbit command is one of 'x', 'y', or 'z'.
It indicates the axis normal to the plane of orbit.
The x, y, z values indicate the center of orbital rotation.
Lines between Points in Space -
DrawLine
WF3D_DrawLine( int relT, float T1, float T2, float r, float g, float b,
float x1, float y1, float z1, float x2, float y2, float z2, float thickness );
Beams between Points in Space -
BeamXYZ - (Same as DrawLine but with thickness = 3.0)
WF3D_BeamXYZ( int relT, float T1, float T2,
float r, float g, float b,
float x1, float y1, float z1,
float x2, float y2, float z2, float thickness );
Beams between objects -
Beam
WF3D_Beam( int relT, float T1, float T2, char *obj1, char *obj2,
float r, float g, float b );
Beam offsets -
BeamOffset
void WF3D_Beam_Offset( float offset );
Raises or lowers the point that beams are drawn to/from objects
(as drawn via the <beam obj1 obj2 ... command).
The value offsets the attachment point in the Y-dimension (usually up/down).
The beam command normally draws to an object's defined origin point.
However, many vehicle object definitions start at y=0.0 (where the tires meet the
road), and work upward from there. If left alone, beams will be drawn to
the bottom of the object, and will often be obscured by terrain.
Instead, you may wish the beam to be drawn toward the top of the vehicle, where
the antenna is. Accomplish this by providing a positive Y offset.
This is a global offset.
Cone-Beams between objects -
ConeBeam
WF3D_ConeBeam( int relT, float T1, float T2, char *obj1, char *obj2,
float r, float g, float b, float beamwidth );
7. Including Files:
You may reference WFL files by:
WF3D_ReadFile( char *fname );
This is identical to the <include fname/> tag in the WFL format.
8. Requesting Time:
Often it is useful to synchronize, or have some notion as to the progress of the
viewer from an application which may not run in real-time. For example, the simulation
may either not want to get too far ahead, or fall behind the real-time clock which
governs the viewer. In such cases, the interactive program can ask the WinFrame3D
viewer for the time by sending the following command on the socket.
float WF3d_TimeQuery();
WinFrame3D will return with the current time in seconds since the start of the viewer
as a floating-point value. This is the same time reference which governs the display
(ex. T1 and T2).
9. Fog Control -
- Normally fog is "on", it's density is set to 0.0002, and it's color is
r=0.3 g=0.3 b=0.5.
- Fog is controlled by command-line options.
- Disable fog by: -fogoff
or: -nofog
- Control fog density by increasing or decreasing the fog-density value:
-fogdensity 0.0002
- Change fog color by:
-fogcolor r g b
For example:
-fogcolor 0.3 0.3 0.5
See Other WF3d Command Line Options.
10. Background Color -
void WF3D_BGcolor( float r, float g, float b );
- Normally background color is r=0.3 g=0.3 b=0.6.
- This command changes the background color to whatever you want.
- Example: WF3D_BGcolor( 0, 0, 0 );
(Makes black background.)
11. Adding Text -
void WF3D_Def_Text( char *typename, float r, float g, float b, float scale,
float thickness, char *text );
... Defines a text object which can be instantiated anywhere, as many times as needed.
As a proper object, it can be moved, rotated, shifted, etc.. Do not forget to instantiate.
Example:
WF3D_Def_Text( "your_text1", 1, 0, 0, 10.0, 2.0, "This is the test." );
WF3D_Instantiate_Obj( "textitem1", "your_text1", 120, 200, 45, 0, 0, 0 );
The name is required, but the other parameters are optional. Scale controls the size of
the text, and defaults to 1.0. Thickness controls the thickness or boldness, and defaults
to 1.0. The r,g,b values control the text color, range between 0.0 and 1.0, and default
to a lime color. The original of the front of the text definition is set at the 0,0,0 origin,
and spaces along the positive X-axis, and z=0, with height in y, starting at y=0.
An alternate method of adding text is shown below. It places text in a single command,
but does not create a named object, so it cannot be moved or manipulated.
void WF3D_Put_Text( char *instname, float r, float g, float b, float scale, float thickness,
float x, float y, float z, float ax, float zy, float az, char *text );
12. Camera Positioning -
You can move and point the camera via the following file or socket commands.
These can be used to pan the camera at predetermined rates and times.
void WF3D_Camera_Move( int moverel, float t1 float t2, float x, float y, float z );
and
void WF3D_Camera_Point( int moverel, float t1 float t2, float x, float y, float z );
13. Removing Objects -
Removing Object Instances:
void WF3D_RemoveObject( int moverel, float T, char *name );
Name is the instance-name of the object to be removed.
T designates the time the object will be removed.
Relative times may be specified with movrel true.
(The time will then be interpreted relative to when the command arrived to the viewer).
Example:
WF3D_RemoveObject( 0, "tank1", 10.5 );
WF3D_RemoveObject( 1, "tank1", 3.5 );
Removing Object Definitions: (This also removes all instances automatically.)
void WF3D_RemoveDefinition( int moverel, float T, char *type_name )
Type_name is the type-name of the object-definition to be removed.
T designates the time the object will be removed.
Relative times may be specified with movrel true.
(The time will then be interpreted relative to when the command arrived to the viewer).
Example:
WF3D_RemoveDefinition( 0, "Tank_T72", 10.5 );
WF3D_RemoveDefinition( 1, "Tank_T72", 3.5 );
Several basic geometric shapes can be quickly defined through the following convenience functions.
- Spheres can be automatically defined with the following command:
void WF3D_Define_Sphere( char *name, int nhemi, float radius, int nslice, int nlayers,
float r, float g, float b, float transp );
Where: name will be the type-name of the newly defined object type.
nhemi is the number of hemispheres, and must be either 1 or 2.
2 draws a complete sphere, while 1 draws a half-sphere.
radius controls the size of the sphere.
nslices and nlayers control the quality and complexity of the sphere
in terms of the number of polygons used to render it. These default to 10 and 8
respectively, unless specified. Generally, the smaller the sphere, the less
detail is needed. Values of 8 and 6 deliver the lowest quality sphere, while
values of 22 and 20 deliver ultra high quality spheres.
r, g, b specify the color in values between 0.0 and 1.0.
transp controls the level of transparency. A value of 1.0 is solid or
non-transparent. A value of 0.0 it totally transparent or invisible.
A semi-transparent sphere can be useful for illustrating the range of radio transmissions
or other forms of influence. On the ground, usually only a half sphere is needed.
(It's orientation may need to be rotated.)
Like all object definitions, the sphere needs to be instantiated.
Any number of a given type can be instantiated and moved.
- Cylinders can be automatically defined with the following command:
WF3D_Define_Cylinder( char *name, float radius, int nslice, float height,
float r, float g, float b, float transp );
Where: name will be the type-name of the newly defined object type.
radius controls the diameter of the cylinder.
nslices controls the quality of the cylinder in terms of the number
of polygons used to render it. It defaults to 20 unless specified.
Generally, the smaller the cylinder, the less detail is needed.
Values of 10-15 deliver the lowest quality cylinder, while values of 40-80
deliver high quality cylinders. Values above 100 are usually overkill.
height controls the length of the cylinder.
r, g, b specify the color in values between 0.0 and 1.0.
transp controls the level of transparency. A value of 1.0 is solid
or non-transparent. A value of 0.0 it totally transparent or invisible.
1.0 is default.
- Disks, Arcs, Wedges can be automatically defined with the following command:
void WF3D_Define_Disk( char *name, float radius, int nslice, float r, float g,
float b, float transp, int fill, float thick,
float ang, float dir );
Where: name will be the type-name of the newly defined object type.
nsegs controls the quality of the disk in terms of the number of polygons
used to render it.
fill controls the outline and interior of the disk.
fill = 0 produces just the outline of the disk, or an arc.
fill = 1 produces just the filled surface of disk or wedge, with no outline.
fill = 2 produces a filled and outlined disk or wedge.
The default fill value is 1.
thickness applies only to the optional outline, and defaults to 1.0.
ang and dir apply to partial disks, which are wedges or arcs.
The ang value specifies the angle subtended by the wedge or arc.
dir controls which direction the wedge points, or is oriented.
Both angles are specified in degrees, and default to 360 (full disk), and 0,
respectively. The 0-degree direction points toward the positive x-axis.
90-degrees points toward the positive y-axis.
r, g, b, transp - specify the color and transparency. Each range 0.0-1.0.
Transparency of 1.0 is solid, 0.0 is invisible.
- Boxes can be automatically defined with the following command:
void WF3D_Define_Box( char *name, float length, float width, float height,
float r, float g, float b, float transp )
15. Scaling Instantiated Objects -
You change the scale of any instantiated object at any time by:
void WF3D_Scale_Object( char *name, int relT, float T1, float scaleamount )
Where: name is the instance-name of the object to be scaled.
T is the time the scaling takes effect.
and scale is the scale factor. (More than one enlarges, less than one reduces size.)
Relative times may be specified with relT = true.
(The time will then be interpreted relative to when the command arrived to the viewer).
You may stretch or shrink an object in one dimension using the scaleobj_x, scaleobj_y,
or scaleobj_z tags as follows:
void WF3D_Scale_Object_X( char *name, int relT, float T1, float scaleamount )
void WF3D_Scale_Object_Y( char *name, int relT, float T1, float scaleamount )
void WF3D_Scale_Object_Z( char *name, int relT, float T1, float scaleamount )
These commands scale the object in the respective dimension independently.
16. Attaching Objects to Other Objects -
You can attach an object to another object so that the objects move together by using
the attach_obj command.
WF3D_AttachOject( obj_instance_name1, obj_instance_name2, relT, t1, t2 );
This causes obj_instance_name1's position to be locked to obj_instance_name2's position.
At time t1, obj_instance_name1 will snap to obj_instance_name2's position, if not
already there, and it will move with obj_instance_name2 as obj_instance_name2 moves.
If t1 and t2 are absolute times, then set relT to 0. Otherwise is t1 is relative to
current time, then set relT to true.
You can display objects in the foreground of the screen that stay in the same place on the
screen regardless of where the camera is pointed. The objects in foreground mode are displayed
in orthonormal projection within a 100x100x100 cube that is always 1 unit away from the camera lens.
Under the normal default mode, objects are displayed in perspective projection within a user-specified
frustum. Perspective viewing renders distant objects smaller than closer objects, while orthonormal
projection renders objects the same size, regardless of distance from the camera. For this reason, the
foreground mode is useful for displaying text, and perhaps console (own-vehicle) displays, gauges, etc.,
which are to remain stationary on the screen. The foreground mode is also known as screen-relative
while the normal perspective or background mode is known as scene-relative.
The orthonormal foreground mode is also useful for any kind of 2D displays in general, such as
2D maps, or even 2D map overlays on a split 3D screen.
To specify objects in the orthonormal foreground mode, toggle into the foreground state with:
WF3D_Set_FGBG_State( 'B' );
Then instantiate the objects, text, etc.. You can switch back to the default background state by:
WF3D_Set_FGBG_State( 'F' );
You can switch back and forth between the two states whenever needed.
The bgfgstate affects only the instantiation process. Once instantiated, an object
remains in the respective display state. Therefore, once an object is instantiated, it can be
manipulated from either state. All of the object constructs are available likewise from both
states.
Related libraries:
Download Header and Object File:
Contents: wf3d.h, wf3d.o [Right-click to save link-target ...]
- All Linux, Mac-OSx and MS-Win PC versions in one package: wf3d_obj.tgz - 573-KB [July 14, 2014]
Or wf3d_obj.zip - 573-KB [July 14, 2014]
|