DATASERV (kgeom) functions


LIBRARY ROUTINE

kgeom_new_object - construct a new geometry object

LIBRARY CALL

kgeom_object *
kgeom_new_object(void)

INPUT

none

OUTPUT

none

RETURN VALUE

a pointer to the constructed object on success, NULL on failure

DESCRIPTION

This function will construct a new geometry object structure and initialize all of its fields with their default values.

Once constructed, the fields of this geometry object can be assigned specific values. For a complete explanation of these fields, see the kgeom_object man page.

Geometry Primitives and Primitive Lists

A geometry primitive contains geometric data which describes a shape in space. Lines, triangles, and spheres, are all considered to be geometric primitives. For a complete description of all the geometry primitives, see the kgeom_primitive man page.

Each geometry object contains a list of such geometry primitives. New primitives can be created using the function kgeom_new_primitive(). Once a new primitive has been created and its data assigned, it can be added to the primitive list of the object using the function kgeom_add_primitive(). A corresponding function kgeom_remove_primitive() allows you to remove a primitive from the primitive list of an object.

The number of primitives which have been added to the primitive list of an object is returned by the function kgeom_number_primitives(). A primitive at a specific position in the primitive list can be retrieved using the function kgeom_get_primitive().

The primitive functions should be the only means used for accessing the primitives on a primitive list. Even though the primitive list of the geometry object could be acccessed directly, it should be considered to be private. By using the primitive list function calls, you can be certain to maintain the integrity of the primitive list.

Reading and Writing Geometry Objects

A geometry object can be written out to a file, or other transport using the function kgeom_write_object(). This function will write out all the object and primitive information to a specified file.

Geometry that has been stored in a file can be read back with the function kgeom_read_object(). This function will construct a new object into which it will read the geometry; it is not necessary to pre-construct an object with the kgeom_new_object() function prior to reading.

Other Geometry Object Functions

A geometry object can be copied using the function kgeom_copy_object().

A geometry object can be destroyed with a call to the function kgeom_geom_blast_object(). This will destroy the object and all of its primitives, freeing all associated memory. Be careful not to access any of the geometry object's data after blasting it.

ADDITIONAL INFORMATION

none

EXAMPLES

This simple code illustrates how a new geometry object would be constructed :

kgeom_object *obj;

obj = kgeom_new_object();

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

$DATASERV/objects/library/kgeom/src/object.c

SEE ALSO

kgeom(3), kgeom_object, kgeom_blast_object, kgeom_copy_object, kgeom_write_object, kgeom_read_object, kgeom_primitive, kgeom_new_primitive, kgeom_add_primitive, kgeom_get_primitive, kgeom_remove_primitive, kgeom_number_primitives

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.