Bulletin Board

99.1 Introduction

The Bulletin Board provides the means by which an application can trace how a model changes in the course of a modeling operation. The bulletin board is stored as arrays of tags of entities and associated arrays of event tokens which describe what has happened to an entity.

Performance issue: This information can be used to improve the performance of the application. For example, to implement incremental graphics or the incremental update of a database. As such, the decision of whether to use the bulletin board is fundamental to the architecture of the application.

The bulletin board can be switched on and off during a session so its effects can be minimised if performance is of prime importance. In many cases the benefits of using the bulletin board far outweigh the cost in terms of performance.

Note: If you do not want to use the bulletin board, you can use pmark entity information to track modelling changes during a Parasolid session instead. In particular, PK_PMARK_ask_entities can tell you which entities would be created, modified, or deleted if you were to move to a given pmark, and PK_PMARK_goto_2 can roll a partition to a given pmark. These functions give you complete control over which entity information is tracked and returned. See Chapter 97, “Rollback”, for more information.

99.2 Using the bulletin board

The entities and events that are recorded on the bulletin board are controlled by the application. Different information can be recorded for different entity classes.

99.2.1 Bulletin board events

A bulletin board event is some specified modification made to an entity (e.g. the entity is transformed or split into two) or the creation or deletion of the entity. The particular events which can be recorded on the bulletin board are the:

Creation of an entity
Deletion of an entity
Splitting of an entity into two entities
Merging of two entities to form a single entity
Transformation of an entity
Copying of an entity
Change to an attribute that is owned by an entity
Transfer of an entity from one entity to another entity
Changing, in some other manner, of an entity

Each time one of the modeling changes listed above happens, Parasolid adds an entry to the bulletin board.

For an example of this functionality, see the code example in the C++\Code Examples\Application Support\Session Management\BB folder, located in example_applications in your Parasolid installation folder.

99.2.2 Bulletin board entity classes

The entity classes that can be recorded on the bulletin board fall into the following groups:

Group	Entity classes
Bodies
Topology	shells faces loops edges vertices regions
Groups
Geometry	surfaces curves points
Transforms
Attribute definitions

99.2.3 Events and entity class combinations

The permissible combinations of events and entity classes are indicated by *

Event	body	topology, group	geometry, transform	attribute definition
Create	*	*	*	*
Delete (“deleet”)	*	*	*
Copy	*	*	*
Transfer		*	*
Merge	*	*
Split	*	*
Transform	*	*	*
Change to Attribute	*	*	*
Change	*	*	*

Note: 1. It is not possible for all bulletin board events to occur to all of the different entity classes, e.g. a point cannot be merged or split as these operations are only possible with topological entities.

2. The name of the field for delete is


deleet

, because


delete

is a reserved word in C++.

3. Groups are considered as separate entities from any of their members. Bulletining of a group happens when members are added or removed from the group, i.e. groups change only when their set of members change and not just when a member of the set changes.

See “Groups and modelling operations on a part” in Chapter 98, “Groups”, for further information on how the members of a group can be changed.

99.2.4 Setting up the bulletin board

PK_BB_create controls what is recorded by the bulletin board for each entity/event combination. The entity/events that are to be recorded are controlled by associating the required entity classes for each event.

PK_BB_set_status then switches the bulletin board on and off, by setting the status argument to one of the following values:

Value	Description
PK_BB_status_on_c	Switch the bulletin board on to record entities
PK_BB_status_off_c	Switch the bulletin board off, and clear its contents
PK_BB_status_user_field_c	Switch the bulletin board on to record entities and user fields

99.2.4.1 Enquiries

PK_BB_askoutputs the current set up of the bulletin board.

PK_BB_ask_status outputs whether the bulletin board is currently recording.

PK_BB_is can be used to determine whether an entity is a bulletin board.

99.2.4.2 Setting the PK_BB_t argument

Only one bulletin board at a time is supported, and PK_BB_create always returns a PK_BB_t argument with the value one.

It is recommended that the PK_BB_t argument be set to one when calling the other Bulletin Board PK functions, although the value is currently ignored.

99.2.5 Output of bulletin board information

To find out what is on the bulletin board, and therefore what changes have taken place in the parts in the session, PK_BB_output_events outputs the events that have occurred since the bulletin board was last emptied.

PK_BB_output_events takes an argument to specify whether the bulletin board is emptied after the bulletin board data is returned.

the bulletin board can be emptied at any time by calling PK_BB_output_events with the empty argument set to PK_LOGICAL_true

The data is returned in five arrays:

Array	Description
events	the event number
entities	contains the tag of the entity involved
event_types	from the PK_BB_event_t range
classes	from the PK_CLASS_t range
user_fields	contains the user fields of the entity involved. The use of this array is optional and depends on whether the user field length is zero or not.

Example:

The bulletin board is set up with PK_BB_create - the create and copy arrays of PK_BB_sf_t contain PK_CLASS_point; PK_BB_set_status turns the bulletin board on (for tags only).

If a point is created and copied, PK_BB_output_events would return two events as follows:

events	entities	event_types	classes
0	249	PK_BB_event_create_c	PK_CLASS_point
1	250	PK_BB_event_copy_c	PK_CLASS_point
1	249	PK_BB_event_copy_c	PK_CLASS_point

Note: 1. Event 0 is the creation of point 249 and event 1 is the copying of point 249 to point 250 (for a copy event the new entity is returned first, then the original entity)

Note: 2. The bulletin board records what actually happened internally within Parasolid during a modeling operation, this may sometimes give unexpected entries

Note: 3. There may be multiple entries for the merge, split, copy and transfer events

[back to top]

99.3 How Parasolid maintains the bulletin board

The bulletin board accumulates events as entities are created, deleted or modified. Each time an event occurs to an entity, the kernel looks for another entry in the bulletin board associated with that entity.

If one already exists there are rules which govern what action the bulletin board takes when two consecutive events occur to an entity (these may not necessarily be consecutive events in the bulletin board). With respect to these rules the events bulletined fall into the following four classes:

Inheritance events - events that have more than one entity associated with them.

Merge - the first entity is the dominant entity and remains through the operation, the other entities are those which were deleted as part of the operation.
Split - the first entity is the entity which was originally split, the other entities are those which were created as part of the operation.
Copy - the first entity is the new entity, the other entity is the entity it was copied from.
Transfer - the first entity is the entity that is transferred, the other entity is the entity which was previously the owner.

Creation and deletion
Alterations - unspecified change, transformation
External changes - change to attributes owned by the entity

The rules which govern the action the bulletin board takes on two consecutive events, are:

If the new event is an inheritance event or an external change then the event is recorded.
If the previous event is an inheritance event or an external change then the event is recorded.
If the previous entry was a creation and

the new event is an alteration, the new event is not recorded as the entity is still new from the last time the bulletin board was emptied.
the new event is deleted, then the create event is removed from the bulletin board and the delete event is not recorded.

If the previous event was an alteration and the new event is a deletion then the alteration event is removed and the entity is recorded as deleted.
If the previous event was a change and the new event is either a change or a transformation then the event remains as a change.
If the previous event was a transformation and

the new event is a transformation, then the two events are combined into one transformation event.
the new event is a change event, then the two events are combined into one change event.

99.3.1 Interaction between events

Certain types of events can have overlapping definitions, this occurs if the bulletin board has been instructed not to record the relevant event type. Therefore depending on what events have been specified, the bulletin board may record a particular event as one or more other events. The events which exhibit this behaviour are:

The split event may be recorded as a change to the parent entity and the creation of the offspring entity.
The merge event may be recorded as a change to the dominant entity and the deletion of the sub-dominant entity.
The transfer event may be recorded as a change to the entity which was transferred.
The copy event may be recorded as a create event to the new entity.
The transformation event may be recorded as a change event.

Records accumulate in this way until the bulletin board is emptied, which clears all the entries from it and starts again (unless the monitoring is turned off entirely).

[back to top]

99.4 The bulletin board and rollback

99.4.1 Session rollback

When a session roll mark is set, this includes details of the bulletin board. When the session is rolled back, the bulletin board is also rolled back to the same point. That is, both the contents and the entity event associations are rolled back, so the bulletin board is consistent with the new state of the session.

99.4.2 Partitioned rollback

When a partition mark is set, the bulletin board is NOT included. This is because a partition mark only refers to certain entities in the session. The bulletin board logs operations which occur on bodies in different partitions, and cannot selectively mark or roll its contents.

Note: Therefore, the bulletin board must be emptied before performing a partition roll - rolling back returns an error if the bulletin board is not empty.

See Chapter 97, “Rollback”, for further information on the rollback functionality.

[back to top]

99.5 Rendering using the bulletin board

Performance issue: An application may want to maintain a picture of a part, which is updated automatically as the part is changed. In principle this could be done by simply redrawing the picture every time the model changes, but in practice this would be unnecessarily time-consuming.

The bulletin board can be used to track how a part changes, so an application can just redraw only the entities that no longer look the same. This process is called incremental graphics.

99.5.1 Incremental graphics

There are two Parasolid facilities used to perform incremental graphics:

The bulletin board records the entities in the model which have been created, deleted or modified.
The rendering functions accept individual faces and edges, allowing less than a whole body to be drawn.

By watching the bulletin board the application can re-draw anything that has been modified or added. To keep the picture properly up to date, deleted items, and the earlier versions of changed items, need to be removed. Note however that the kernel does not provide any specific support for this part of the task: it is up to the application to remember (usually in some sort of graphical data structure) what entities are being displayed, and to remove them from the picture when necessary.

Incremental graphics can be implemented using faceting and the bulletin board together. For example, a part can be faceted and the bulletin board can be used to identify faces that have changed after an operation. The changed faces can then be re-faceted, without re-faceting the whole part.

See Section 107.2.16, “Incremental faceting” for information on the functions available for drawing entities.

[back to top]

<<< Groups

Chapters

Archives >>>