opennurbs_instance.h
/* $NoKeywords: $ */
/*
//
// Copyright (c) 1993-2012 Robert McNeel & Associates. All rights reserved.
// OpenNURBS, Rhinoceros, and Rhino3D are registered trademarks of Robert
// McNeel & Associates.
//
// THIS SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY.
// ALL IMPLIED WARRANTIES OF FITNESS FOR ANY PARTICULAR PURPOSE AND OF
// MERCHANTABILITY ARE HEREBY DISCLAIMED.
//
// For complete openNURBS copyright information see <http://www.opennurbs.org>.
//
////////////////////////////////////////////////////////////////
*/
#if !defined(OPENNURBS_INSTANCE_INC_)
#define OPENNURBS_INSTANCE_INC_
/*
Description:
An ON_InstanceDefinition defines the geometry used by
instance references.
See Also:
ON_InstanceRef
*/
class ON_CLASS ON_InstanceDefinition : public ON_Geometry
{
ON_OBJECT_DECLARE(ON_InstanceDefinition);
public:
// IDEF_UPDATE_TYPE lists the possible relationships between
// the instance definition geometry and the archive
// (m_source_archive) containing the original defition.
enum IDEF_UPDATE_TYPE
{
static_def = 0,
embedded_def = 1,
// As of 7 February, "static_def" and "embedded_def"
// and shall be treated the same. Using "static_def"
// is prefered and "embedded_def" is obsolete.
// The geometry for the instance definition
// is saved in archives, is fixed and has no
// connection to a source archive.
// All source archive information should be
// empty strings and m_source_archive_checksum
// shoule be "zero".
linked_and_embedded_def = 2,
// The geometry for the instance definition
// is saved in archives. Complete source
// archive and checksum information will be
// present. The document setting
// ON_3dmIOSettings.m_idef_link_update
// determines if, when and how the instance
// definition geometry is updated by reading the
// source archive.
linked_def = 3,
// The geometry for this instance definition
// is not saved in the archive that contains
// this instance definition. This instance
// definition geometry is imported from a
// "source archive" The "source archive" file
// name and checksum information are saved
// in m_source_archive and m_source_archive_checksum.
// If file named in m_source_archive is not available,
// then this instance definition is not valid and any
// references to it are not valid.
force_32bit_idef_update_type = 0xFFFFFFFF
};
// Converts and integer into an IDEF_UPDATE_TYPE enum.
static IDEF_UPDATE_TYPE IdefUpdateType(int i);
// Bits that identify subsets of the instance defintion
// fields. These bits are used to determine which fields to
// set when an ON_InstanceDefinition class is used to
// modify an existing instance definition.
enum
{
no_idef_settings = 0,
idef_name_setting = 1, // m_name
idef_description_setting = 2, // m_description
idef_url_setting = 4, // all m_url_* fields
idef_units_setting = 8, // m_us and m_unit_scale
idef_source_archive_setting = 0x10, // all m_source_*, layer style, update depth fields
idef_userdata_setting = 0x20,
all_idef_settings = 0xFFFFFFFF
};
public:
ON_InstanceDefinition();
~ON_InstanceDefinition();
// virtual ON_Object overrides
ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
// virtual ON_Object::Dump override
void Dump( ON_TextLog& ) const;
ON_BOOL32 Write(
ON_BinaryArchive& binary_archive
) const;
ON_BOOL32 Read(
ON_BinaryArchive& binary_archive
);
ON::object_type ObjectType() const;
unsigned int SizeOf() const;
// virtual ON_Geometry overrides
int Dimension() const;
ON_BOOL32 GetBBox(
double* boxmin,
double* boxmax,
int bGrowBox = false
) const;
ON_BOOL32 Transform(
const ON_Xform& xform
);
// virtual
ON_UUID ModelObjectId() const;
// Interface
const wchar_t* Name() const;
void SetName( const wchar_t* name );
const wchar_t* Description() const;
void SetDescription( const wchar_t* description );
const wchar_t* URL() const;
void SetURL( const wchar_t* url );
const wchar_t* URL_Tag() const;
void SetURL_Tag( const wchar_t* url_tag );
ON_UUID Uuid() const;
void SetUuid( ON_UUID uuid );
void SetBoundingBox( ON_BoundingBox bbox );
// list of object ids in the instance geometry table.
ON_SimpleArray<ON_UUID> m_object_uuid;
/*
Description:
If the instance definition is linked or embedded, use
SetSource to specify the source archive.
Parameters:
source_archive - [in] name of source archive
checksum - [in] check sum used to detect changed.
Generally, you will pass ON_CheckSum::UnsetCheckSum
for this argument and Rhino will handle setting
the checksum to the appropriate value at the appropriate
time.
source_type - [in]
If source_archive and checksum are empty, then
source_type is ignored and static_def will be used.
If source_archive is a nonempty string and checksum
is set, then source_type must be either
linked_and_embedded_def or linked_def. If you
are changing the source archive of a valid idef,
then simply pass this->IdefUpdateType().
Remarks:
See the IDEF_UPDATE_TYPE comments for more details.
*/
void SetSourceArchive(
const wchar_t* source_archive,
ON_CheckSum checksum,
IDEF_UPDATE_TYPE update_type
);
/*
Description:
Destroys all source archive information.
Specifically:
* m_source_archive is set to the empty string.
* m_source_bRelativePath is set to false
* The alternative source archive path is set
to the empty string.
* m_source_archive_checksum.Zero() is used to
destroy all checksum information.
* m_idef_update_type is set to static_def.
*/
void DestroySourceArchive();
/*
Returns:
Name of source archive.
*/
const wchar_t* SourceArchive() const;
/*
Returns:
Check sum of source archive.
*/
ON_CheckSum SourceArchiveCheckSum() const;
const ON_UnitSystem& UnitSystem() const;
/*
Description:
Use this function to specify an alternate location to
look for a linked instance defininition archive if it
cannot be found in the location specified by m_source_archive.
Parameters:
alternate_source_archive_path - [in]
alterate location. pass null to delete the alternate path.
bRelativePath - [in]
true if alternate_source_archive_path is a relative path.
*/
void SetAlternateSourceArchivePath(
const wchar_t* alternate_source_archive_path,
bool bRelativePath
);
/*
Description:
If there is an alternate location to look for a linked instance
defininition archive when it cannot be found in the location
specified by m_source_archive, then function will return the
alterate location.
Parameters:
alternate_source_archive_path - [out]
bRelativePath - [out]
true if alternate_source_archive_path is a relative path.
*/
bool GetAlternateSourceArchivePath(
ON_wString& alternate_source_archive_path,
bool& bRelativePath
) const;
/*
Description:
Sets m_us and m_unit_scale.
*/
void SetUnitSystem( ON::unit_system us );
void SetUnitSystem( const ON_UnitSystem& us );
/*
Returns:
True if this is a linked instance definition with
layer settings information.
*/
bool HasLinkedIdefLayerSettings() const;
/*
Description:
Set linked instance definition reference file layer settings.
Parameters:
layer_settings - [in/out]
input: layer settings read from the linked file.
output: layer settings to use in the context of the idef.
*/
void UpdateLinkedIdefReferenceFileLayerSettings( unsigned int layer_count, ON_Layer** layer_settings );
/*
Description:
Set linked instance definition parent layer information.
Typically this is done just before the linked idef is
saved to a file.
Parameters:
linked_idef_parent_layer - [in]
*/
void UpdateLinkedIdefParentLayerSettings( const ON_Layer* linked_idef_parent_layer );
const ON_Layer* LinkedIdefParentLayerSettings() const;
/*
Description:
When a linked instance definition is read and its layers are added to the
context when the idef exists, runtime layer ids may need to be changed
when an id collision occures. In this case, use this function to
inform the linked instance definition of the map from runtime layer
id to the layer id found in the linked file.
Parameters:
id_map - [in]
The first id in the pair is the layer id in the current context
where the idef is being used.
The second id in the pair is the layer id found in the linked file.
*/
void UpdateLinkedIdefReferenceFileLayerRuntimeId( const ON_UuidPairList& id_map );
/*
Description:
Set linked instance definition layer settings.
Typically this is done just before the linked idef is
saved to a file.
Parameters:
layer_settings - [in]
Layer settings in the context where the linked idef is being used.
Remarks:
Linked idefs save the original layer informtion from the linked file.
In the context where the idef is used, some of those settings (color,
visibility, ...) can be modified. This function saves those modifications
so the can be applied the next time the linked idef is read.
*/
void UpdateLinkedIdefLayerSettings( unsigned int layer_count, const ON_Layer*const* layer_settings );
public:
ON_UUID m_uuid; // unique id for this instance definition
ON_wString m_name; // The "name" is for human comfort.
// It can be empty and duplicates
// may exist. Instance reference use
// m_uuid to find instance definitions.
ON_wString m_description;
ON_wString m_url;
ON_wString m_url_tag; // UI link text for m_url
#if defined(ON_32BIT_POINTER)
private:
// 24 January 2011:
// Because the Rhino 4 and 5 SDKs are fixed, the offset of
// existing fields cannot be changed and the m_reserved1
// value has to be located in different places for
// 32 and 64 bit builds.
unsigned int m_reserved1;
#endif
public:
ON_BoundingBox m_bbox;
ON_UnitSystem m_us;
// Note: the embedded_def type is obsolete.
// To avoid having to deal with this obsolete type in
// your code, using ON_InstanceDefintion::IdefUpdateType()
// to get this value. The IdefUpdateType() function
// with convert the obsolte value to the correct
// value.
IDEF_UPDATE_TYPE m_idef_update_type;
IDEF_UPDATE_TYPE IdefUpdateType() const;
int m_idef_update_depth; // Controls how much geometry is read when
// a linked idef is updated.
// 0: read everything, included nested linked idefs
// 1: skip nested linked idefs.
ON_wString m_source_archive; // filename used to update idef
// (it can be empty or relative)
bool m_source_bRelativePath; // True if the filename in m_source_archive is
// a relative the location of the 3dm file
// containing this instance definition.
// A static or linked_and_embedded idef must have m_layer_style = 0
// A linked idef must have m_layer_style = 1 or 2
// 0 = unset
// 1 = active (linked idef layers will be active)
// 2 = reference (linked idef layers will be reference)
unsigned char m_idef_layer_style;
private:
unsigned char m_reserved2[2];
#if defined(ON_64BIT_POINTER)
private:
// 24 January 2011:
// Because the Rhino 4 and 5 SDKs are fixed, the offset of
// existing fields cannot be changed and the m_runtime_sn
// value has to be located in different places for
// 32 and 64 bit builds.
unsigned int m_reserved1;
#endif
public:
ON_CheckSum m_source_archive_checksum; // used to detect when idef is out of
// synch with source archive.
};
/*
Description:
An ON_InstanceRef is a reference to an instance definition
along with transformation to apply to the definition.
See Also:
ON_InstanceRef
*/
class ON_CLASS ON_InstanceRef : public ON_Geometry
{
ON_OBJECT_DECLARE(ON_InstanceRef);
public:
ON_InstanceRef();
/////////////////////////////////////////////////////////////
//
// virtual ON_Object overrides
//
ON_BOOL32 IsValid( ON_TextLog* text_log = NULL ) const;
ON_BOOL32 Write(
ON_BinaryArchive& binary_archive
) const;
ON_BOOL32 Read(
ON_BinaryArchive& binary_archive
);
ON::object_type ObjectType() const;
/////////////////////////////////////////////////////////////
//
// virtual ON_Geometry overrides
//
int Dimension() const;
ON_BOOL32 GetBBox(
double* boxmin,
double* boxmax,
int bGrowBox = false
) const;
ON_BOOL32 Transform(
const ON_Xform& xform
);
// virtual ON_Geometry::IsDeformable() override
bool IsDeformable() const;
// virtual ON_Geometry::MakeDeformable() override
bool MakeDeformable();
/////////////////////////////////////////////////////////////
//
// Unique id of the instance definition (ON_InstanceDefinition)
// in the instance definition table that defines the geometry
// used by this reference.
ON_UUID m_instance_definition_uuid;
// Transformation for this reference.
ON_Xform m_xform;
// Bounding box for this reference.
ON_BoundingBox m_bbox;
// Tolerance to use for flagging instance xforms
// as singular.
static const double m_singular_xform_tol;
};
#endif
ON_Object::IsValid
virtual ON_BOOL32 IsValid(ON_TextLog *text_log=NULL) const =0
ON_InstanceDefinition::m_url
ON_wString m_url
Definition: opennurbs_instance.h:308
ON_InstanceRef::m_singular_xform_tol
static const double m_singular_xform_tol
Definition: opennurbs_instance.h:436
ON_Object::SizeOf
virtual unsigned int SizeOf() const
ON_InstanceDefinition::m_source_bRelativePath
bool m_source_bRelativePath
Definition: opennurbs_instance.h:343
ON_Geometry::Transform
virtual ON_BOOL32 Transform(const ON_Xform &xform)
ON_Object::ModelObjectId
virtual ON_UUID ModelObjectId() const
ON_SimpleArray< ON_UUID >
ON_Geometry::MakeDeformable
virtual bool MakeDeformable()
ON_InstanceDefinition::m_name
ON_wString m_name
Definition: opennurbs_instance.h:302
ON_InstanceDefinition
Definition: opennurbs_instance.h:27
ON_InstanceDefinition::m_description
ON_wString m_description
Definition: opennurbs_instance.h:306
ON_Object::ObjectType
virtual ON::object_type ObjectType() const
ON_wString
Definition: opennurbs_string.h:700
ON_Geometry::IsDeformable
virtual bool IsDeformable() const
ON_InstanceDefinition::m_source_archive
ON_wString m_source_archive
Definition: opennurbs_instance.h:341
ON_Geometry
Definition: opennurbs_geometry.h:36
ON_InstanceDefinition::m_idef_update_type
IDEF_UPDATE_TYPE m_idef_update_type
Definition: opennurbs_instance.h:332
ON_InstanceRef::m_instance_definition_uuid
ON_UUID m_instance_definition_uuid
Definition: opennurbs_instance.h:426
ON_InstanceDefinition::m_url_tag
ON_wString m_url_tag
Definition: opennurbs_instance.h:309
ON_InstanceRef::m_xform
ON_Xform m_xform
Definition: opennurbs_instance.h:429
ON_InstanceDefinition::m_bbox
ON_BoundingBox m_bbox
Definition: opennurbs_instance.h:322
ON_Geometry::Dimension
virtual int Dimension() const =0
ON_Layer
Definition: opennurbs_layer.h:20
ON_InstanceDefinition::m_us
ON_UnitSystem m_us
Definition: opennurbs_instance.h:324
ON_Object::Read
virtual ON_BOOL32 Read(ON_BinaryArchive &binary_archive)
ON_Object::Write
virtual ON_BOOL32 Write(ON_BinaryArchive &binary_archive) const
ON_BoundingBox
Definition: opennurbs_bounding_box.h:25
ON_InstanceRef::m_bbox
ON_BoundingBox m_bbox
Definition: opennurbs_instance.h:432
ON_InstanceDefinition::m_idef_layer_style
unsigned char m_idef_layer_style
Definition: opennurbs_instance.h:352
ON_InstanceDefinition::IDEF_UPDATE_TYPE
IDEF_UPDATE_TYPE
Definition: opennurbs_instance.h:36
ON_Xform
Definition: opennurbs_xform.h:28
ON_InstanceRef
Definition: opennurbs_instance.h:380
ON_InstanceDefinition::m_source_archive_checksum
ON_CheckSum m_source_archive_checksum
Definition: opennurbs_instance.h:368
ON_InstanceDefinition::m_uuid
ON_UUID m_uuid
Definition: opennurbs_instance.h:301
ON_InstanceDefinition::m_object_uuid
ON_SimpleArray< ON_UUID > m_object_uuid
Definition: opennurbs_instance.h:143
ON_UUID
Definition: opennurbs_uuid.h:31
ON_UnitSystem
Definition: opennurbs_string.h:1068
ON_InstanceDefinition::m_idef_update_depth
int m_idef_update_depth
Definition: opennurbs_instance.h:336
ON_TextLog
Definition: opennurbs_textlog.h:22
ON_BinaryArchive
Definition: opennurbs_archive.h:731
ON_UuidPairList
Definition: opennurbs_array.h:1481
ON_CheckSum
Definition: opennurbs_string.h:273
ON_Geometry::GetBBox
virtual ON_BOOL32 GetBBox(double *boxmin, double *boxmax, int bGrowBox=false) const =0
ON_Object::Dump
virtual void Dump(ON_TextLog &) const