A base class for bridging modelers into SMTK. More...

#include <Session.h>

Inheritance diagram for smtk::model::Session:

Collaboration diagram for smtk::model::Session:

Public Member Functions
	smtkTypeMacroBase (smtk::model::Session)

	smtkSuperclassMacro (smtk::model::Session)

	smtkCreateMacro (smtk::model::Session)

virtual std::string	name () const
	Return the name of the session type (i.e., the name of the modeling kernel). More...

virtual std::string	className () const

smtk::common::UUID	sessionId () const
	Return the session ID for this instance of the session. More...

int	transcribe (const EntityRef &entity, SessionInfoBits flags, bool onlyDangling=true, int depth=-1)
	Transcribe an entity from a foreign modeler into an SMTK storage Resource. More...

virtual SessionInfoBits	allSupportedInformation () const
	Return a bit vector describing what types of information can be transcribed. More...

const DanglingEntities &	danglingEntities () const
	Return the map from dangling entityrefs to bits describing their partial transcription state.

void	declareDanglingEntity (const EntityRef &ent, SessionInfoBits present=0)
	Mark an entity, ent, as partially transcribed. More...

virtual int	setup (const std::string &optName, const StringList &optVal)
	Set configuration options on the session. More...

ResourcePtr	resource () const
	Return a reference to the resource that owns this Session.

smtk::io::Logger &	log ()
	Return the log (obtained from the model resource).

virtual	~Session ()
	Destructor.

virtual bool	splitEntity (const EntityRef &from, const EntityRefs &to) const

virtual bool	mergeEntities (const EntityRefs &from, EntityRef &to) const

virtual bool	splitAttributes (const EntityRef &from, const EntityRefs &to) const
	Called when an entity is being split so that attribute assignments can be updated. More...

virtual bool	mergeAttributes (const EntityRefs &from, EntityRef &to) const
	Called when an entity is being split so that attribute assignments can be updated. More...

virtual bool	removeGeneratedProperties (const EntityRef &ent, SessionInfoBits propFlags)
	This is used by the resource when erasing a model entity. More...

virtual bool	splitProperties (const EntityRef &from, const EntityRefs &to) const
	Called when an entity is being split or cut into one or more descendants. More...

virtual bool	mergeProperties (const EntityRefs &from, EntityRef &to) const
	Called when one or more entities are being merged or joined into a descendant. More...

virtual std::string	defaultFileExtension (const Model &model) const
	Return a filename extension (including ".") appropriate for saving model. More...

Static Public Member Functions
static std::string	staticClassName ()

Protected Member Functions
	Session ()
	Default constructor. This assigns a random session ID to each Session instance.

virtual SessionInfoBits	transcribeInternal (const EntityRef &entity, SessionInfoBits flags, int depth=-1)
	Transcribe information requested by flags into entity from foreign modeler. More...

void	setSessionId (const smtk::common::UUID &sessId)
	Set the session ID. More...

void	setResource (Resource *resource)
	Inform this instance of the session that it is owned by resource.

virtual EntityPtr	addEntityRecord (const EntityRef &entRef)
	Subclasses implement this; it should add a record for entRef to the resource.

virtual ArrangementHelper *	createArrangementHelper ()
	Subclasses implement this; it should return a new ArrangementHelper subclass instance. More...

int	findOrAddRelatedEntities (const EntityRef &entRef, SessionInfoBits flags, ArrangementHelper *helper)
	Recursively called by transcribeInternal until no new entities are encountered.

virtual int	findOrAddCellAdjacencies (const CellEntity &entRef, SessionInfoBits request, ArrangementHelper *helper)
	Subclasses implement this; it should add boundary, bounding, embedded, and embeddor cells of the current cell.

virtual int	findOrAddCellUses (const CellEntity &entRef, SessionInfoBits request, ArrangementHelper *helper)
	Subclasses implement this; it should add use records of the current cell.

virtual int	findOrAddOwningCell (const UseEntity &entRef, SessionInfoBits request, ArrangementHelper *helper)
	Subclasses implement this; it should add the current use's owning cell.

virtual int	findOrAddShellAdjacencies (const UseEntity &entRef, SessionInfoBits request, ArrangementHelper *helper)
	Subclasses implement this; it should add shells bounded by or bounding the given use.

virtual int	findOrAddUseAdjacencies (const ShellEntity &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual int	findOrAddGroupOwner (const Group &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual int	findOrAddFreeCells (const Model &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual int	findOrAddRelatedModels (const Model &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual int	findOrAddPrototype (const Instance &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual int	findOrAddRelatedModels (const SessionRef &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual int	findOrAddRelatedGroups (const EntityRef &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual int	findOrAddRelatedInstances (const EntityRef &entRef, SessionInfoBits request, ArrangementHelper *helper)

virtual SessionInfoBits	findOrAddArrangements (const EntityRef &entRef, EntityPtr entRec, SessionInfoBits flags, ArrangementHelper *helper)
	Subclasses implement this to finalize arrangement information for entRef using the helper.

virtual SessionInfoBits	updateProperties (const EntityRef &entRef, EntityPtr entRec, SessionInfoBits flags, ArrangementHelper *helper)
	Subclasses implement this to update transcribed (not user-specified) properties of entRef.

virtual SessionInfoBits	updateTessellation (const EntityRef &entRef, SessionInfoBits flags, ArrangementHelper *helper)
	Sublasses implement this to update the tessellation of the given entRef. More...

virtual SessionIOPtr	createIODelegate (const std::string &format)
	Subclasses may override this method to export additional state. More...

Protected Attributes
DanglingEntities	m_dangling

smtk::common::UUID	m_sessionId

Resource *	m_resource { nullptr }

Friends
class	Resource

Detailed Description

A base class for bridging modelers into SMTK.

SMTK can act as a session between other (foreign) solid modelers and client applications. The session must provide techniques for attaching UUIDs to foreign model entities (on its own or by using facilities provided by the foreign modeler) and for obtaining notification when foreign model entities are modified or destroyed. In extreme cases, the SMTK model resource must be reset after each modeling operation to guarantee a consistent model.

Instances of Session subclasses should be registered with a model using Resource::sessionModel(). Then, when an entity cannot be resolved from a UUID created by the session, the transcribe method will be invoked to request that the session add an entry.

This class is not intended for external use. Public methods are intended for invocation by the Resource instance which owns the session. Protected methods are either called internally or by subclasses in order to track UUIDs for which there is only partial information in Resource.

See also: smtk::model::SessionInformation; smtkDeclareModelingKernel smtkImplementsModelingKernel

Member Function Documentation

◆ allSupportedInformation()

SessionInfoBits smtk::model::Session::allSupportedInformation ( ) const

virtual

Return a bit vector describing what types of information can be transcribed.

This is used to determine when an entity has been fully transcribed into storage and is no longer "dangling."

Reimplemented in smtk::session::vtk::Session, and smtk::session::polygon::Session.

◆ createArrangementHelper()

ArrangementHelper * smtk::model::Session::createArrangementHelper ( )

protectedvirtual

Subclasses implement this; it should return a new ArrangementHelper subclass instance.

The caller is responsible for deleting it.

◆ createIODelegate()

SessionIOPtr smtk::model::Session::createIODelegate ( const std::string & format )

protectedvirtual

Subclasses may override this method to export additional state.

Importers (e.g., LoadJSON) and exporters (e.g., SaveJSON) will call this method to obtain a session I/O class instance specific to the given format. If a valid SessionIO shared-pointer is returned, it will be dynamically cast to a format-specific subclass and given the opportunity to provide additional information to be imported/exported to/from the session.

This default implementation is provided since most sessions will not need additional state.

Reimplemented in smtk::session::vtk::Session, and smtk::session::polygon::Session.

◆ declareDanglingEntity()

void smtk::model::Session::declareDanglingEntity	(	const EntityRef &	ent,
		SessionInfoBits	present = `0`
	)

Mark an entity, ent, as partially transcribed.

Subclasses should call this method when a UUID has been assigned to a model entity but ent.resource() has not yet been populated with all of the information about the entity. The information which is present in ent.resource() should be passed but will default to zero (i.e., the UUID exists in some other entity's relations but has no records in resource itself).

The entity is added to the list of dangling entities and will be removed from the list when a call to transcribeInternal indicates that Session::allSupportedInformation() is now present in resource.

◆ defaultFileExtension()

std::string smtk::model::Session::defaultFileExtension ( const Model & model ) const

virtual

Return a filename extension (including ".") appropriate for saving model.

Subclasses of session should override this method. If a method returns the empty string, it indicates that the model requires no "native" model file. (The polygon session is an example of this where all information is saved in the SMTK file.)

Reimplemented in smtk::session::vtk::Session, smtk::session::polygon::Session, smtk::session::mesh::Session, and smtk::model::DefaultSession.

◆ mergeAttributes()

bool smtk::model::Session::mergeAttributes	(	const EntityRefs &	from,
		EntityRef &	to
	)		const

virtual

Called when an entity is being split so that attribute assignments can be updated.

The default implementation removes all attributes from from and assigns those same attributes to each entity of to.

◆ mergeProperties()

bool smtk::model::Session::mergeProperties	(	const EntityRefs &	from,
		EntityRef &	to
	)		const

virtual

Called when one or more entities are being merged or joined into a descendant.

Sessions are responsible for overriding this to handle propagation of any property values.

Return true on success and false on failure.

The base class implementation simply copies the union of the "pedigree" properties from the ancestors to the descendant.

◆ name()

std::string smtk::model::Session::name ( ) const

virtual

Return the name of the session type (i.e., the name of the modeling kernel).

Subclasses override this method by using the smtkDeclareModelingKernel and smtkImplementsModelingKernel macros.

◆ removeGeneratedProperties()

bool smtk::model::Session::removeGeneratedProperties	(	const EntityRef &	ent,
		SessionInfoBits	propFlags
	)

virtual

This is used by the resource when erasing a model entity.

Subclasses should implement this and erase all of the string, integer, and floating-point properties (as specified by propFlags) that their modeling kernel allows them to reproduce when transcribe() is called. The properties should only be erased from ent's model resource, not from the underlying modeling kernel.

Do not erase properties like name, color, and visibility unless they are stored by the underlying modeling kernel in addition to SMTK.

Return true when at least one property was removed, false otherwise.

◆ sessionId()

smtk::common::UUID smtk::model::Session::sessionId ( ) const

Return the session ID for this instance of the session.

Sessions are ephemeral and tied to a particular machine so they should generally not be serialized.

◆ setSessionId()

void smtk::model::Session::setSessionId ( const smtk::common::UUID & sessId )

protected

Set the session ID.

Do not call this unless you are preparing the session to be a remote mirror of a modeling session (for, e.g., client-server operation).

◆ setup()

int smtk::model::Session::setup	(	const std::string &	optName,
		const StringList &	optVal
	)

virtual

Set configuration options on the session.

Subclasses may override this method to accept configuration options specific to their backends. When optName and optVal are acceptable, the method returns 1; otherwise a zero or negative value is returned.

◆ splitAttributes()

bool smtk::model::Session::splitAttributes	(	const EntityRef &	from,
		const EntityRefs &	to
	)		const

virtual

Called when an entity is being split so that attribute assignments can be updated.

The default implementation removes all attributes from from and assigns those same attributes to each entity of to.

◆ splitProperties()

bool smtk::model::Session::splitProperties	(	const EntityRef &	from,
		const EntityRefs &	to
	)		const

virtual

Called when an entity is being split or cut into one or more descendants.

Sessions are responsible for overriding this to handle propagation of any property values.

Return true on success and false on failure. It is not a failure for an entity to be missing properties. Depending on the context, it may be an error for a destination entity to already have a property when it is inconsistent with the value on from.

The base class implementation simply copies the "pedigree" property to the descendants.

◆ transcribe()

int smtk::model::Session::transcribe	(	const EntityRef &	entity,
		SessionInfoBits	requested,
		bool	onlyDangling = `true`,
		int	depth = `-1`
	)

Transcribe an entity from a foreign modeler into an SMTK storage Resource.

On input, the entity will not be valid but if transcription is successful, the requested records in the entity's Resource will be valid. If requested includes SESSION_ENTITY_TYPE, then entity.isValid() should return true after this call.

Only honor requests for entity IDs listed as dangling unless onlyDangling is false (default is true). This prevents expensive requests by Resource instances over many Sessions.

The return value is 0 upon failure and non-zero upon success. Failure occurs when any requested bits of information that are in Sessione::allSupportedInformation() are not transcribed, or when requested is 0.

◆ transcribeInternal()

SessionInfoBits smtk::model::Session::transcribeInternal	(	const EntityRef &	entRef,
		SessionInfoBits	flags,
		int	depth = `-1`
	)

protectedvirtual

Transcribe information requested by flags into entity from foreign modeler.

This method should return a non-zero value upon success. Upon success, flags should be modified to represent the actual information transcribed (as opposed to what was requested). This should always be at least the information requested but may include more information.

Currently, it really only makes sense to call this method on a Model (i.e., not an edge, face, etc.); entire models at a time are retranscribed.

Subclasses may override this method. If they do not, they should implement the virtual relationship helper methods.

Reimplemented in smtk::session::vtk::Session, smtk::session::polygon::Session, smtk::session::mesh::Session, and smtk::model::DefaultSession.

◆ updateTessellation()

SessionInfoBits smtk::model::Session::updateTessellation	(	const EntityRef &	entRef,
		SessionInfoBits	flags,
		ArrangementHelper *	helper
	)

protectedvirtual

Sublasses implement this to update the tessellation of the given entRef.

This method will only be called when transcribe() is asked to include the tessellation.

The documentation for this class was generated from the following files:

/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/model/Session.h
/home/docs/checkouts/readthedocs.org/user_builds/smtk/checkouts/latest/smtk/model/Session.cxx

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Function Documentation

◆ allSupportedInformation()

◆ createArrangementHelper()

◆ createIODelegate()

◆ declareDanglingEntity()

◆ defaultFileExtension()

◆ mergeAttributes()

◆ mergeProperties()

◆ name()

◆ removeGeneratedProperties()

◆ sessionId()

◆ setSessionId()

◆ setup()

◆ splitAttributes()

◆ splitProperties()

◆ transcribe()

◆ transcribeInternal()

◆ updateTessellation()