DIVE distribution module

Dive 3 Reference Manual
Web site: <http://www.sics.se/dive/manual/distr.html>

Olof Hagsand - <olof@sics.se>
The Swedish Institute of Computer Science, Stockholm October, 1995

1. Introduction

This document describes the Dive distribution module functional interface. It requires some background knowledge about C and Dive[1].

2. On distribution of entities

After an entity or an entity hierarchy has been created and initialized locally with the functions described elsewhere [2,3], it is published, that is, distributed and made available to the distributed environment so that it can be replicated at other sites. After an entity has been published it is said to be distributed, and the object should only be modified by operations defined in this document.

In this way, entities go through the following states:

Local - After creation the entities may be initialized and manipulated by local functions [2].
Published - After publishing, all operations on the entities must be made via the distribution interface described in this manual.

Note that if local operations are performed on entities during the distributed phase, the entity will only be updated at the local site, not at other sites having the replica.

2. Publishing entities

Publishing is the act of making entities available in the distributed environment to other users. The following functions publish local (already created) entities:

http://www.sics.se/dive/manual/cref.d.html#distr_entity_new http://www.sics.se/dive/manual/cref.d.html#distr_new_top http://www.sics.se/dive/manual/cref.d.html#distr_new_only

3. Requesting and updating published entities

3.1 Sub-levels

When requesting and updating entities, a sub_level parameter can be given to indicate how large part of an object hierarchy is requested or updated. The sub_level type may have the following values:

SUB_LEVEL_ALL -- The entity and all its subs: the complete hierarchy.
SUB_LEVEL_NONE -- The entity only, without subs.
SUB_LEVEL_ONE -- The entity and one level of sub objects in an hierarchy.

The following functions requests and "republishes" entities. A "republishing" is due to a change or to a prior request from some other peer.

http://www.sics.se/dive/manual/cref.d.html#distr_entity_request http://www.sics.se/dive/manual/cref.d.html#distr_entity_update http://www.sics.se/dive/manual/cref.d.html#distr_entity_change

4. Joining and leaving groups

Any Dive entity can be associated with a multicast group, but the Dive API currently only supports groups associated with worlds. The functions below defines how to create new worlds and bind multicast addresses to them and how to move actors between worlds.

http://www.sics.se/dive/manual/cref.d.html#distr_world_connect http://www.sics.se/dive/manual/cref.d.html#distr_world_disconnect http://www.sics.se/dive/manual/cref.d.html#distr_actor_world_connect http://www.sics.se/dive/manual/cref.d.html#distr_actor_world_change

5. Operations for all entities

The following functions are a collection of general services for all types of entities (ie, views, dive_obj, etc):

6. Geometric Operations on Dive objects

The following geometric operations on dive_obj's are the "published" counterparts of the local geometric operations described in [6]. Apart from the "transport" functions, they all set the coordinates of the objects and do not interpolate the positions for collisions check or gateway detection. Thus the semantics of these functions are like "teleporting".

7. Other operations on Dive_obj

The following functions offers various services for manipulating dive_objects.

http://www.sics.se/dive/manual/cref.d.html#distr_scale http://www.sics.se/dive/manual/cref.d.html#distr_texture http://www.sics.se/dive/manual/cref.d.html#distr_material http://www.sics.se/dive/manual/cref.d.html#distr_flags http://www.sics.se/dive/manual/cref.d.html#distr_invisible http://www.sics.se/dive/manual/cref.d.html#distr_wireframe http://www.sics.se/dive/manual/cref.d.html#distr_nograsp http://www.sics.se/dive/manual/cref.d.html#distr_clipping_plane

Many of the functions above will be generalized to all entities in further releases.

8. Miscellaneous

Miscellaneous functions for manipulating different entities:

http://www.sics.se/dive/manual/cref.d.html#distr_text http://www.sics.se/dive/manual/cref.d.html#distr_image http://www.sics.se/dive/manual/cref.d.html#distr_texture_index http://www.sics.se/dive/manual/cref.d.html#distr_material_index

References

[1] Dive 3.2 file format interface.

[2] Dive 3.2 Reference manual, the DIVE Entity interface.

[3] Dive 3.2 File input interface.

[4] Dive 3.2 Property interface.

[5] Dive 3.2 Callback interface.

[6] Dive 3.2 Entity interface.