Previous Topic Index Next Topic
[API function]

FSOUND_Geometry_AddPolygon

Adds a polygon to the geometry database between FSOUND_3D_Update calls.
This function can take a triangle or a quad, based on whether 'p4' is NULL or not.
It is also able to be defined as an 'openning' polygon, which can serve as doorways or
windows.

signed char F_API FSOUND_Geometry_AddPolygon(
float *p1,
float *p2,
float *p3,
float *p4,
float *normal,
unsigned int mode,
float *openingfactor
);

Parameters

p1 Pointer to the polygons vertex. This must be a pointer to an array of 3 floats.
This value cannot be NULL.
p2 Pointer to the polygons vertex. This must be a pointer to an array of 3 floats.
This value cannot be NULL.
p3 Pointer to the polygons vertex. This must be a pointer to an array of 3 floats.
This value cannot be NULL.
p4 Pointer to the polygons vertex. This must be a pointer to an array of 3 floats.
This CAN be NULL, if you are specifying a triangle and not a quad.
normal Pointer to the polygons vertex. This must be a pointer to an array of 3 floats.
This value CAN be NULL. If it is, then a nomral is computed based for you.
This is only to save time computing a normal internally, it does not matter which
direction it faces. (ie what winding)
mode This is a setting of bits defined by FSOUND_GEOMETRY_MODES to determine what type
of polygon it is, ie reflective or an opening for example.
openingfactor Pointer to a polygon opening factor. This value is only relevant if
FSOUND_GEOMETRY_OPENING or FSOUND_GEOMETRY_OPENING_REFERENCE is supplied, and is
ignored otherwise. Valid ranges are and from 0 to 1. 0 is closed, 1 is fully
open.
Remember that FSOUND_GEOMETRY_OPENING is only relevant to the previous polygon.
if this value is NULL, then this polygon is discarded and there is no hole.

Return Value

On success, TRUE is returned.
On failure, FALSE is returned.

Remarks

This is a buffered command. It only takes effect when FSOUND_3D_Update is called.
At this point all polygons are cleared, and another batch has to be prepared, either through
using FSOUND_Geometry_AddPolygon, or FSOUND_Geometry_AddList.
--------
A more efficient methohd to add geometry is through FSOUND_Geometry_AddList. This is a pre-
stored method of adding polygons as a batch in the geometry renderers native format, instead
of individually which is more time consuming.
--------
What do FSOUND_GEOMETRY_OPENING and FSOUND_GEOMETRY_OPENING_REFERENCE mean??
These 2 methods are useful when wanting to cut a hole in a polygon, for a door or window for
example, and dont want to add the extra polygons it would take to do it in geometry.
If you are calling FSOUND_Geometry_AddPolygon every frame, therefore rebuilding the audio
scene every frame, then it is a good idea to use FSOUND_GEOMETRY_OPENING. The value you
pass in is COPIED, and is not pointed to internally.
If you are building a list, and once the list is built, you want access to the opening factor,
then it would be a good idea to use FSOUND_GEOMETRY_OPENING_REFERENCE. This means when you
are using FSOUND_Geometry_AddList every frame, you still can alter the opening factors you
set previously (when building the list with FSOUND_Geometry_AddPolygon). As always keep the
scope of the pointer relevant to where you call the function from if it is declared on the
stack, otherwise it will cause unpredictable results if the value suddenly goes out of scope
and becomes corrupted.
This is also the case if you had the pointer stored inside a dynamically allocated section
memory, and the memory holding your pointer is freed. If FSOUND_Geometry_AddList processes
this pointer it will lead to unpredictable results.
There is no reason not to use FSOUND_GEOMETRY_OPENING if you are building a list, it is
very reasonable to do so if you want to reduce the polygon count of the audibility database.
You just wont have access to the opening factor once the list is built.
--------
As an efficiency note, an opening polygon is NOT a boolean polygon cut which is considerably
more expensive than just supplying a pre-cut database. It does not add polygons which can be
time consuming.
It is just a transparency which is overlaid onto the previous polygon. Sound tests, upon
contacting the opening, do not process the parent (except to get material information).

See Also

FSOUND_3D_Update , FSOUND_Geometry_AddList , FSOUND_Geometry_AddPolygon , FSOUND_Geometry_List_Begin , FSOUND_Geometry_List_Create , FSOUND_Geometry_List_End , FSOUND_Geometry_Material_Create , FSOUND_Geometry_Material_Set , FSOUND_GEOMETRY_MODES

This document copyright ©Firelight Multimedia, 1999-2001. All rights reserved.
Generated Thu Sep 13 00:18:09 2001 by SourceDoc v0.10, the automated source code documenter.