The geWorld object is a container for holding BSP data, Actors, Entities, dynamic lights, and more. It is responsible for rendering these items in order, efficiently. It provides collision handling APIs.
Anything which is 3D is rendered through geWorld.
geBoolean geWorld_AddActor(geWorld *World, geActor *Actor, uint32 Flags, uint32 UserFlags)
Description: Adds an Actor to a world.
Parameters:
| World | World to add the actor to | ||||||||||
| Actor | Actor to be added | ||||||||||
| Flags |
Any combination of the following:
|
||||||||||
| UserFlags | Arbitrary flags reserved for the user |
Returns: GE_TRUE on success, GE_FALSE on failure.
geBoolean geWorld_AddBitmap(geWorld *World, geBitmap *Bitmap)
Description: Adds a bitmap to the world.
Parameters:
| World | World to add the bitmap to |
| Bitmap | Bitmap to add |
Returns: GE_TRUE on success, GE_FALSE on failure.
Remarks: Until a bitmap is added to the world, it may not be used to render user added polygons (geWorld_AddPoly). Bitmaps are added to the world implicitly when Actors are added to the world, and when a world is created with a BSP file which contains bitmaps.
geFog *geWorld_AddFog(geWorld *World)
Description: Creates a volumetric fog object in the world.
Parameters:
| World | World to create the fog in |
Returns: A valid geFog object on success, NULL on failure.
Remarks: This API differs from the container model outlined in the overview for technical reasons. It will be reviewed at a later date, and may be altered to conform.
geLight *geWorld_AddLight(geWorld *World)
Description: Adds a dynamic light to the world.
Parameters:
| World | World to add the light to |
Returns: A valid geLight object on success, NULL on failure.
Remarks: This API differs from the container model outlined in the overview for technical reasons. It will be reviewed at a later date, and may be altered to conform.
gePoly *geWorld_AddPoly(geWorld *World, GE_LVertex *Vertices, int Count, geBitmap *Bitmap, gePoly_Type Type, uint32 RenderFlags, float Scale)
Description: Adds a polygon to the world for rendering.
Parameters:
| World | World to add the polygon to | ||||||||
| Vertices | Array of vertices, in clockwise order, that make up the polygon. The polygon will be ordered in the world for rendering based upon its geometric center. Note that while the vertices of the polygon have a field for alpha level, only the first vertex's alpha value is considered when rendering. This is because most cards do not support iterated alpha values. | ||||||||
| Count | Count of vertices in the vertex array. Must be at least 3, if Type is not GE_TEXTURED_POINT. If Type is GE_TEXTURED_POINT, then the Count must be 1. | ||||||||
| Bitmap | Bitmap to texture the polygon with. This parameter can be NULL, in which case the polygon is rendered gouraud shaded. | ||||||||
| Type |
One of:
|
||||||||
| RenderFlags | |||||||||
| Scale | Scaling value that is applied to the dimensions of the polygon if Type is GE_TEXTURED_POINT. |
Returns: A valid gePoly object on success, NULL on failure.
Remarks: This API differs from the container model espoused in the overview for reasons of efficiency. The API is intended to give users reasonably efficient access to extra polygon rendering in the world, on a frame by frame basis, where the addition and removal of such polygons is expected to happen with great rapidity. To preserve this efficiency, we have left the object partially dissected.
geBoolean geWorld_AddPolyOnce(geWorld *World, GE_LVertex *Vertices, int Count, geBitmap *Bitmap, gePoly_Type Type, uint32 RenderFlags, float Scale)
Description: Adds a polygon to the world for rendering.
Parameters:
| World | World to add the poly to |
| Vertices | See geWorld_AddPoly |
| Count | See geWorld_AddPoly |
| Bitmap | See geWorld_AddPoly |
| Type | See geWorld_AddPoly |
| RenderFlags | See geWorld_AddPoly |
| Scale | See geWorld_AddPoly |
Returns: GE_TRUE on success, GE_FALSE on failure.
Remarks: This API is very similar to geWorld_AddPoly. It differs in that the polygon is added to the world for one frame only. After the world is rendered in that frame, the polygon will be removed automatically.
geBoolean geWorld_BitmapIsVisible(const geWorld *World, const geBitmap *Bitmap)
Description: Tests to see if a bitmap was used in the previous frame for any rendered polygon.
Parameters:
| World | World to test bitmap in |
| Bitmap | Bitmap to test |
Returns: GE_TRUE if the Bitmap was used in the previous frame, GE_FALSE otherwise.
Remarks: This API was added to allow clients to test a bitmap to see whether or not it is being rendered currently so that processing on the Bitmap may be foregone in the interests of efficiency. For example, if you are running procedural routines on a set of bitmaps, you may only which to run those procedurals if the bitmap is actually being rendered currently.
geBoolean geWorld_Collision(geWorld *World, const geVec3d *Mins, geVec3d *Maxs, const geVec3d *Front, geVec3d *Back, uint32 Flags, uint32 UserFlags, GE_CollisionCB *CollisionCB, void *Context, GE_Collision *Collision)
Description: Does collision detection against various objects in the world.
Parameters:
| World | World to do collision test against | ||||||||
| Mins | Minimum values of an axial aligned bounding box to collide against the world. If this value is NULL, then the collision is considered a ray collision test. The bounding box dimensions are relative to the Front/Back vector, not in absolute world coordinates. If you provide a bounding box, the entire box is collided against the world. | ||||||||
| Maxs | Maximum values of an axial aligned bounding box to collide against the world. If Mins are specified, then the Maxs must be specified as well. | ||||||||
| Front | Start of the ray or box movement to test. | ||||||||
| Back | End of the ray or box movement to test | ||||||||
| Flags |
Combination of:
|
||||||||
| UserFlags | Flags to mask against user flags in collideable objects, such as Actors. These flags are masked against the UserFlags on those objects, and the collision test is made if the result is non-zero. Otherwise, the object is ignored. This is a means of fast rejection for potential collideable sets, and for preventing collisions conditionally for arbitrary purposes. | ||||||||
| CollisionCB | Callback function to be called for each object that we collide against. The callback function has the opportunity to accept or reject the collision. If the collision is rejected, then the collision testing proceeds against the other objects in the world, until a collision is accepted, or there are no more collisions. If this parameter is NULL, then the first object collided against is returned. | ||||||||
| Context | Arbitrary context pointer which is passed to the CollisionCB function on each call. | ||||||||
| Collision | Resulting collision information structure. |
Returns: GE_TRUE if there was a collision, GE_FALSE otherwise.
geWorld *geWorld_Create(geVFile *File)
Description: Creates a world.
Parameters:
| File |
geVFile to read the world from. If this parameter is NULL, an empty world is created with a constant size, containing a single empty space. The world then is essentially just a container that renders the subobjects. If the File parameter is not NULL, then it must point to a BSP file, and a world is created from this. Geometry, texture information, lighting data, visibility data, entities, etc are all read and instantiated. |
Returns: A valid geWorld object on success, NULL on failure.
Remarks: The world must be added to a geEngine with geEngine_AddWorld before it can be rendered.
void geWorld_Free(geWorld *World)
Description: Destroys a world.
Parameters:
| World | World to be destroyed. |
Returns: void.
Remarks: Destroys the world, and all it contains. This includes bitmaps, Actors, polygons, lights and fog objects. Note that this function differs from the Create/Destroy model discussed in the overview. This will be changed before the final release of the engine.
geBitmap *geWorld_GetBitmapByName(geWorld *World, const char *Name)
Description: Retrieves a world texture by name.
Parameters:
| World | World to retrieve the bitmap from |
| Name | Name of the bitmap to retrieve. |
Returns: geBitmap object, if found, NULL otherwise.
Remarks: This API only applies to bitmaps that were used to texture the world geometry in the editor. The name of the bitmap is the name that appears in the editor to the level designer. The API was provided as a means for the applications programmer to gain access to world bitmaps so as to run procedural algorithms on them.
geBoolean geWorld_GetContents(geWorld *World, const geVec3d *Position, const geVec3d *Mins, const geVec3d *Maxs, uint32 Flags, uint32 UserFlags, GE_CollisionCB *CollisionCB, void *Context, GE_Contents *Contents)
Description: Gets content information about a position and bounding box from a world.
Parameters:
| World | A valid geWorld object | ||||||
| Position | Position in the world to gather information about | ||||||
| Mins | Minimum values of an axial aligned bounding box. If this parameter is NULL, then the test is performed only on the single point of the Position parameter. If the bounding box is supplied, then the function can return multiple contents for the different regions of the bounding box. | ||||||
| Maxs | Maximum values of the axial aligned bounding box. If Mins is not NULL, then this parameter must not be NULL. | ||||||
| Flags |
Any combination of:
|
||||||
| UserFlags | UserFlags to mask against objects in the volume of the bounding box/point. | ||||||
| CollisionCB | Collision callback function to be called for each object found in the bounding region. | ||||||
| Context | Context passed to the CollisionCB on each occurence of an object/space found in the bounding region. | ||||||
| Contents | Contents structure that is filled in with information about the contents of the region. |
Returns: GE_TRUE if there were any non-emtpy contents in the region specified, GE_FALSE otherwise.
Remarks: The workings of this function are very similar to geWorld_Collision. In particular, the collision callback function, Flags and UserFlags behave identically.
geEntity_EntitySet geWorld_GetEntitySet(geWorld *World, const char *SetName)
Description: Retrieves a named set of entites from the world.
Parameters:
| World | World to get the set from |
| SetName | Name of the set to search for |
Returns: A geEntity_EntitySet if one is found, NULL otherwise.
Remarks: Currently, the world has one entity set for each named type of entity that is included in the BSP file by the level designer. The name of the set is the name of the type used in the header file that the editor parses. See the overview for more information on entities.
geBoolean geWorld_(geWorld *World)
Description:
Parameters:
| World |
Returns: GE_TRUE on success, GE_FALSE on failure.