For example, consider the simple application file myapp.c:
#include <stdio.h>
#include "wf3d.h" /* Include the WF3D headers. */
main( int argc, char **argv )
{
/* --- My application initialization code can go here. --- */
WF_Init( argc, argv ); /* Initialize and open the WF3D window. */
while (1)
{
/* --- My application code can go here. --- */
WF_FrameUpdate(); /* Display updated frame. */
}
}
Compile with:
cc -L/usr/X11R6/lib myapp.c wf3d.o -lpthread -lGLU -lGL -lXmu -lXext -lX11 -lm -lpthread -o myapp.exeThe 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.
2. Defining Object Types:
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 verices are floating-point.
Objects can be defined with triangular polygons and/or quadralateral 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 quadralaterals 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.
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 );
3. Instantiating Objects:
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.
4. Moving Objects:
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 idicate the center of orbital rotation.
5. Drawing Lines or Radio Beams:
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 obscurred 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 identicle 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( "mytext1", 1, 0, 0, 10.0, 2.0, "This is the test." ); WF3D_Instantiate_Obj( "textitem1", "mytext1", 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 bettween 0.0 and 1.0, and default to a lime color. The original of the front of the text defintion 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 interpretted 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 interpretted relative to when the command arrived to the viewer). Example: WF3D_RemoveDefinition( 0, "Tank_T72", 10.5 ); WF3D_RemoveDefinition( 1, "Tank_T72", 3.5 );
14. Spheres, Cylinders, Disks, Boxes -
Several basic geometric shapes can be quickly defined through the following convenience functions.