stepw.hpp

Go to the documentation of this file.

#ifndef _STEPW_HEADER_
#define _STEPW_HEADER_
class stepw_ER;
 
//! \defgroup step_write Step Write Functions
//! \brief Exported APIs for STEP Write Library
 
//! \ingroup step_write
//! \brief Initializes a file to be written.
//! \param[in] inFileName : Step File to write
//! \param[in] inOriginatingSystem : optional, designation of Originating system. Will be written in file header
//! \param[in] inSchema : specifies a protocol. Supported input : 1 for AP203(E1), 2 for AP214, 3 for AP203E2, 4 for AP242E1, 5 for AP242E4, 0 to adapt to content that will be written.
//! \remark AP203 will be used by default. AP214 will be used if colors are written. AP242 will be used if FDT are written.
//! \return dtkNoError : the file has been correctly initialized.
//! \return dtkErrorAPINotStarted : API was not started.
//! \return dtkErrorVersionNotSupported : input schema isn't supported.
//! \return dtkErrorLicence : licence checking has failed.
DtkErrorStatus stepw_InitFile( const Dtk_string& inFileName, const char* inOriginatingSystem = " user ", const int inSchema = 0 );
 
//! \ingroup step_write
//! \brief Sets STEP file header fields value.
//! \param[in] inNumItem : 0 description, 1 author, 2 organisation, 3 system, 4 authorization.
//! \param[in] inValItem : the value to be set. If empty, switch back to default settings for this field.
//! \return dtkNoError : value has been ccorectly set for this header field.
//! \return dtkErrorUnspecified : inNumItem is not a supported case.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_SetHeaderData( const int inNumItem, const wchar_t* inValItem );
 
//! \ingroup step_write
//! \brief Sets STEP file header fields value.
//! \param[in] inNumItem : 0 description, 1 author, 2 organisation, 3 system, 4 authorization.
//! \param[in] inValItem : the value to be set. If empty, switch back to default settings for this field.
//! \return dtkNoError : value has been ccorectly set for this header field.
//! \return dtkErrorUnspecified : inNumItem is not a supported case.
DtkErrorStatus stepw_SetHeaderData( const int inNumItem, const Dtk_string& inValItem );
 
//! \ingroup step_write
//! \brief Activates/Deactivates writing of FDT.
//! \param[in] inMode : FDT representation mode, -1 graphics only, 0 no writing, 1 fully semantic (with graphics).
//! \param[in] inPolyline : FDT presentation mode  (graphic output), 1 minimal (placeholder), 2 polyline, 3 tessellated.
//! \return dtkNoError : the mode has been correctly activated/deactivated.
//! \return dtkErrorUnspecified : input mode isn't supported. 
//! \return dtkErrorLicence : licence checking has failed.
DtkErrorStatus stepw_SetModeFdt( const int inMode, const int inPolyline = 2 );
 
//! \ingroup step_write
//! \brief Activates/Deactivates writing of properties : User Attributes, Product Data.
//! \param[in] inMode : determines what input attributes or properties will be written. 0 no writing, 1 attributes ( stored in Dtk_Info ) and product data, 2 same as 1, with also metadata (Dtk_MetaData::TypeFileProperty and Dtk_MetaData::TypeUnknown are filtered), 3 same as 2, without any Dtk_Metadata filtering
//! \return dtkNoError : the mode has been correctly activated/deactivated.
//! \return dtkErrorUnspecified : input mode isn't supported. 
DtkErrorStatus stepw_SetModeProp( const int inMode );
 
//! \ingroup step_write
//! \brief Selects a mode for topological 3D items naming policy (shells, faces, edges ).
//! \param[in] inMode : 0 no writing (empty name), 1 use name recorded in Dtk_Info, 2 use ID recorded in Dtk_Info (as "no [ID]").
//! \return dtkNoError : the mode has been correctly activated/deactivated.
//! \return dtkErrorUnspecified : input mode isn't supported. 
DtkErrorStatus stepw_SetModeItemName( const int inMode );
 
//! \ingroup step_write
//! \brief Selects a mode of writing compact or compressed step files.
//! \param[in] inMode : 0 normal mode, 1 output a compressed .stp.Z file (ZIP algorithm), 2 output an archive .stpa file.
//! \return dtkNoError : the mode has been correctly activated/deactivated.
//! \return dtkErrorUnspecified : input mode isn't supported.
DtkErrorStatus stepw_SetModeCompress( const int inMode );
 
//! \ingroup step_write
//! \brief On a solid or shell, allows the spreading of its first available face graphical attributes to the whole solid/shell.
//! \remark If the whole solid/shell has a color defined, this has no effect.
//! \param[in] inMode : true to activate, false to deactivate.
//! \return dtkNoError : the mode has been correctly activated/deactivated.
//! \return dtkErrorUnspecified : input mode isn't supported. 
DtkErrorStatus stepw_SetModeInfoFirstFace( bool inModeInfoFirstFace );
 
//! \ingroup step_write
//! \brief Sets file units in which the geometries, properties are to be written.
//! \details To be called before stepw_Init3DPart. It applies on all Parts following its call.
//! \param[in] inLength : Length Unit, 0 or 1 MM (default), 2 CM, 3 M, 4 KM, 5 IN(INCH), 6 FT(FOOT).
//! \param[in] inAngle  : Angle Unit, 0 Radian (default), 1 Degree.
//! \warning : all 3D data and values are assumed to be defined in the chosen units.
//! \return dtkNoError : the unit has been correctly set.
//! \return dtkErrorUnspecified : input value isn't supported. 
Dtk_ErrorStatus stepw_SetContextUnit( const int inLength, const int inAngle = 0 );
 
 
//! \ingroup step_write
//! \brief Sets file units in which the geometries, properties are to be written, and apply the conversion factor (from MM).
//! \details To be called before stepw_Init3DPart. It applies on all Parts following its call.
//! \param[in] inLength : Length Unit, 0 or 1 MM (default), 2 CM, 3 M, 4 KM, 5 IN(INCH), 6 FT(FOOT).
//! \warning : STEP writer will convert all 3D data and values to the defined length unit.
//! \return dtkNoError : the unit has been correctly set.
//! \return dtkErrorUnspecified : input value isn't supported. 
Dtk_ErrorStatus stepw_SetConversionLengthUnit( const int inLength );
 
//! \ingroup step_write
//! \brief Sets length tolerance for the 3D geometry (uncertainty).
//! \details To be called before stepw_Init3DPart, applies on all Parts till new call.
//! \param[in] inTol : tolerance value, must be positive. 
//! \remark Default applied tolerance is 0.005.
//! \return dtkNoError : the tolerance was correctly set. 
//! \return dtkErrorUnspecified : input value is negative.
Dtk_ErrorStatus stepw_SetContextTolerance( const double inTol );
 
//! \ingroup step_write
//! \brief Creates a unique file name for an external reference - applies to the current session (stepw_InitFile to stepw_EndFile).
//! \return "inFileName" if the input name wasn't registered as a file name yet.
//! \return "inFileName--i" if the input name was already registered as a file name. i is a integer set to make the name unique.
Dtk_string stepw_GiveUniqueFileName( const Dtk_string& inFileName );
 
//! \ingroup step_write
//! \brief Declares a product to be written as an external reference (separated file).
//! \param[in] inProductName : name of product to be referenced externally.
//! \param[in] inFileName : name of file in which its content will be written.
//! \param [out] outID : returned unique identifier for a product. To be used in other calls to identify it.
//! \param[in] inInstCompID : optional, defines a user identifier for this product.
//! \details If a sequence stepw_InitProduct - stepw_EndProduct is then called with outID identifier, it automatically produces
//! another file, with that name, in the same path as the master file.
//! \brief An external reference is written in the current file (only one per file) if this product is used in
//!  an instance or if WriteExternalReference is explicitly called.
//! \warning Must be called before first use or first call to InitProduct.. or WriteExternalReference for this product.
//! \return dtkNoError if the product was correctly registered as an external reference. 
//! \return dtkErrorUnspecified if product already written not as external reference.
Dtk_ErrorStatus stepw_AddExternalReference( const Dtk_string& inProductName, const Dtk_string& inFileName, int& outID, Dtk_ID inInstCompId = 0 );
 
//! \ingroup step_write
//! \brief Writes a product as an external reference. Only one per file for a given product.
//! \brief Applies only on a product which has previously been declared as external by AddExternalReference.
//! \see stepw_AddExternalReference.
//! \param[in] inID : the identifier of the product. Must repeat the ID of the product given by AddExternalReference.
//! \details It is not necessary to call it : the first instance that uses this product will call automatically this function.
//! \return dtkNoError : the external reference has been correctly written.
//! \return dtkOutOfRange : inID does not identify a product.
//! \return dtkErrorUserBreak : external reference for this product has alredy already written.
//! \return dtkErrorUnspecified : the product was not declared by AddExternalReference.
Dtk_ErrorStatus stepw_WriteExternalReference( const int inID );
 
//! \ingroup step_write
//! \brief Checks if a product (known by its unique name), is already registered.
//! \return -1 : a product with this name isn't registered yet.
//! \return positive value : the identifier of the product alredy registered with this name.
int stepw_WhichProductID( const Dtk_string& inProductName );
 
//! \ingroup step_write
//! \brief Creates a unique product name.
//! \remark if inProductName is an empty Dtk_string, it is inteprated as "Product".
//! \return "inProductName" if the input name wasn't registered as a product name yet.
//! \return "inProductName--i" if the input name was already registered as a product name. i is a integer set to make the name unique.
Dtk_string stepw_GiveUniqueProductName( const Dtk_string& inProductName );
 
//! \ingroup step_write
//! \brief Initializes the definition context of a product.
//! \warning assigned name must be unique in the whole step file.
//! \see stepw_WhichProductID, stepw_GiveUniqueProductName
//! \param[in] inProductName : name to be assigned to the product.
//! \param[out] outAssignedID : assigned unique identifier of the product. To be used in other calls to identify it.
//! \param[in] inProductUserID : optional, if positive, defines a user identifier for this product.
//! \return dtkNoError : product context has been correctly initialized.
//! \return dtkErrorUnspecified : error in calling sequence.
DtkErrorStatus stepw_InitProduct( const Dtk_string& inProductName, int& outAssignedID, Dtk_ID inProductUserID = 0 );
 
//! \ingroup step_write
//! \brief Sets the LayerInfosSet to refer to when writing the current product. It uses its mapping between layer identifier and name.
//! \details 3D shapes can be assigned to a layer (through a layer index, in Dtk_Info). The Dtk_LayerInfoSet can further qualify those layers, by assigning them a name.
//! \details Setting the LayerInfoSet for the product has to happen after stepw_InitProduct, and before any calls to stepw_Write3DPartBody, to be taken into account.
//! \param[in] inLayerInfoSet : Pointer to the LayerInfosSet to refer to, in order to assign names to layers.
//! \return dtkNoError : LayerInfosSet has been correctly set for current product context.
//! \return dtkErrorUnspecified : error in calling sequence.
//! \return dtkErrorNullPointer : inLayerInfoSet is null.
DtkErrorStatus stepw_SetProductLayerInfosSet( const Dtk_LayerInfosSetPtr inLayerInfoSet );
 
//! \ingroup step_write
//! \brief Adds an instance of a product ( child ) in an assembly product ( father ).
//! \param[in] inFatherProductID : unique identifier of the father product, provided by stepw_InitProduct.
//! \param[in] inChildProductID  : unique identifier of the child product, provided by stepw_InitProduct.
//! \param[in] inPosition : the relative position of the child product instance, in the father product.
//! \param[in] inInstanceName : name to be assigned to the instance.
//! \return dtkNoError instance has been correctly added.
//! \return dtkErrorUnspecified : the child product do not exist yet (so the instance is not registered).
DtkErrorStatus stepw_AddInstance( const int inFatherProductID, const int inChildProductID, const Dtk_transfo& inPosition, const Dtk_string& inInstanceName );  // 0 OK, -1 ERROR
 
//! \ingroup step_write
//! \brief Adds an instance of a product ( child ) in an assembly product ( father ), with provided attributes.
//! \param[in] inFatherProductID : unique identifier of the father product, provided by stepw_InitProduct.
//! \param[in] inChildProductID  : unique identifier of the child product, provided by stepw_InitProduct.
//! \param[in] inPosition : the relative position of the child product instance, in the father product.
//! \param[in] inInstanceName : name to be assigned to the instance.
//! \param[in] inInstanceInfo : set of information to be attached to the instance, contains attributes (Dtk_Val).
//! \return dtkNoError instance has been correctly added.
//! \return dtkErrorUnspecified : the child product do not exist yet (so the instance is not registered).
DtkErrorStatus stepw_AddInstanceWithInfo( const int inFatherProductID, const int inChildProductID, const Dtk_transfo& inPosition, const Dtk_string& inInstanceName, const Dtk_InfoPtr& inInstanceInfo );
 
//! \ingroup step_write
//! \brief Adds an instance of a product ( child ) in an assembly product ( father ), with provided attributes.
//! \param[in] inFatherProductID : unique identifier of the father product, provided by stepw_InitProduct.
//! \param[in] inChildProductID  : unique identifier of the child product, provided by stepw_InitProduct.
//! \param[in] inPosition : the relative position of the child product instance, in the father product.
//! \param[in] inInstanceName : name to be assigned to the instance.
//! \param[in] inInstanceInfo : set of information attached to the instance, contains attributes (Dtk_Val).
//! \param[out] outInstanceID : the assigned identifier to the created instance.
//! \param[in] inInstanceUserID : optional, the identifier the user wants to provide to the instance, that will be use in addition to the one assigned by this library.
//! \param[in] inReferenceDesignator : optional, additional name identification field for the instance.
//! \return dtkNoError instance has been correctly added.
//! \return dtkErrorUnspecified : the child product do not exist yet (so the instance is not registered).
DtkErrorStatus stepw_AddInstanceWithInfo( const int inFatherProductID, const int inChildProductID, const Dtk_transfo& inPosition, const Dtk_string& inInstanceName, const Dtk_InfoPtr& inInstanceInfo,
int& outInstanceID, const int inInstanceUserID = 0, const Dtk_string& inReferenceDesignator = "" );
 
 
//! \deprecated Use stepw_SetInstanceUserID instead.
SetAsDeprecated( "2025.4", "Use stepw_SetInstanceUserID instead." )
DtkErrorStatus stepw_SetAnchorInstance( const int inInstanceID, const int inInstanceUserID );
 
//! \ingroup step_write
//! \brief Sets the designated instance its user-defined identifier.
//! \param[in] inInstanceID : the already assigned identifier of the designated instance.
//! \param[in] inInstanceUserID :the identifier the user wants to provide to the instance, that will be use in addition to the one assigned by this library.
//! \return dtkNoError user-defined identifier has been correctly set.
//! \return dtkErrorUnspecified : the provided instance identifier does not identify a registered instance.
DtkErrorStatus stepw_SetInstanceUserID( const int inInstanceID, const int inInstanceUserID );
 
//! \deprecated Use stepw_WhichInstanceID instead.
SetAsDeprecated( "2025.4", "Use stepw_WhichInstanceID instead." )
int  stepw_AnchorInstanceID( const int inUserID );
 
//! \ingroup step_write
//! \brief Checks if an instance (known by its user-defined identifier), is already registered.
//! \return 0 : an instance with this user-defined identifier isn't registered yet.
//! \return strictly positive value : the identifier of the instance alredy registered with this user-defined identifier.
int  stepw_WhichInstanceID( const int inUserID );
 
//! \ingroup step_write
//! \brief Defines properties to be attached directly to the product : considers the list of Dtk_Val in the Dtk_Info.
//! \param[in] inInfo : the Dtk_Info which brings the Dtk_Val objects to be written as properties.
//! \param[in] inItem : 0 dispatched between part (PDS) and product (PD), 1 on part only, 2 on product only.
//! \details PDS = PRODUCT_DEFINITION_SHAPE or part, PD = PRODUCT_DEFINITION or product.
//! \warning : must be called before stepw_Init3DPart of the product to be populated.
//! \details dispatch is done according to CAX-IF recommended practices for Geometric and Assembly Validation Properties.
//! \return dtkNoError : properties has been correctly attached. 
//! \return dtk_ErrorOutOfRange : inItem value is not supported.
//! \return dtkErrorUnspecified : error in calling sequence.
DtkErrorStatus stepw_SetPartProperties( const Dtk_InfoPtr& inInfo, const int inItem );
 
//! \ingroup step_write
//! \brief Sets attachment mode for next property writing : the whole Part, or to the following entity to be written.
//! \details Entities eligible for properties as metadata are : Dtk_Body, Dtk_Mesh.
//! \details this mode is to be set for each entity, it is reset by stepw_End3DPart and by each writing of an entity with properties.
//! \param[in] inMode : 0 attach property to the whole Part (default), 1 attach property to a body or mesh entity to be written.
//! \return dtkNoError : the mode has been correctly set.
//! \return dtkErrorOutOfRange : input mode isn't supported.
Dtk_ErrorStatus stepw_InitPropertySet( const int inMode );
 
//! \ingroup step_write
//! \brief Adds a roperty to a part (default), or to an entity, according to InitPropertySet mode.
//! \details Properties on the whole part can represent either "Product Data" or a property of any kind.
//! \details "Product Data" are predefined properties, their reserved titles are : "Part Number", "Nomenclature", "Description", "Definition", "Revision", "Document" or "Source".
//! \details All are optional (when absent, a default value is set), required to be TEXT,
//! \details "Source" must take these values : "MADE" or "BOUGHT" otherwise it is ignored.
//! \details Entity properties will be attached to the next written entity, so, to be called before writing the entity of attachment.
//! \details Entities eligible for properties as metadata are : Dtk_Body, Dtk_Mesh.
//! \param[in] inProperty : the MetaData to be written with the 3D Part.
//! \return dtkNoError : the property has been correctly added.
//! \return dtkErrorNullPointer : inProperty is null.
Dtk_ErrorStatus stepw_Add3DPartProperty( const Dtk_MetaDataPtr& inProperty );
 
//! \ingroup step_write
//! \brief Initializes the writing of a 3D part for the designated product.
//! \details Each product must have a 3D part, even empty : started by stepw_Init3DPart, ended by stepw_End3DPart. The 3D part can contain multiple geometries (body, mesh, wireframe).
//! \param[in] inProductID : unique identifier of the product, provided by stepw_InitProduct.
//! \return dtkNoError if done, dtkErrorOutOfRange if no call to stepw_InitProduct was done previously, or ID wrong
DtkErrorStatus stepw_Init3DPart( const int inProductID );
 
//! \ingroup step_write
//! \brief Initializes the context to write entities in a node.
//! \details Typical entity that needs encapsulation in a node is FDT.
//! \param inNodeID : the identifier attached to this node, must be positive and unique in the scope of a product.
void stepw_InitNodeContext( const int inNodeID );
 
//! \ingroup step_write
//! \brief Initializes the context to write entities in a node.
//! \param inNodeInfo : additional information/attributes to qualify the node (color, layer, invisibility).
//! \param inNodeID : the identifier attached to this node, must be positive and unique in the scope of a product.
void stepw_InitNodeContext( const int inNodeID, const Dtk_InfoPtr& inNodeInfo );
 
//! \ingroup step_write
//! \brief Ends current node context.
void stepw_EndNodeContext( const int unused = 0 );
 
Dtk_ErrorStatus stepw_SetNextSubBody( const int mode );
 
//! \ingroup step_write
//! \brief Writes a body of a 3D part (3D content of a product), of any kind (solid, shell / faces, wireframe / points).
//! \param[in] inBody : the body to be written.
//! \return dtkNoError : the body has been correctly written.
//! \return dtkErrorUnspecified : part context hasn't been initialized.
//! \return dtkErrorNullPointer : inBody is null.
DtkErrorStatus stepw_Write3DPartBody( const Dtk_BodyPtr& inBody );
 
//! \ingroup step_write
//! \brief Writes a body of a 3D part (3D content of a product), associated with a mesh.
//! \details The mesh is assumed to be the result of computing tessellation on the body in case of association : its items can be bound with items of the body.
//! \warning not recommended for STEP versions before AP242.
//! \param[in] inBody : the body to be written.
//! \param[in] inMesh : the mesh to be written, ignored if null.
//! \param[in] inMode : mode of association, 0 as additional representation (default), 1 as alternate geometry (ignored before AP242).
//! \return dtkNoError : the body has been correctly written.
//! \return dtkErrorUnspecified : part context hasn't been initialized.
//! \return dtkErrorNullPointer : inBody is null.
DtkErrorStatus stepw_Write3DPartBodyWithMesh( const Dtk_BodyPtr& inBody, const Dtk_MeshPtr& inMesh, const int inMode = 0 );
 
//! \ingroup step_write
//! \brief Writes a body as a construction geometry of a 3D part, of any kind (solid, shell / faces, wireframe / points).
//! \details Usually used to complement FDT definition.
//! \param[in] inBody : the body to be written.
//! \return dtkNoError : the body has been correctly written.
//! \return dtkErrorUnspecified : part context hasn't been initialized.
//! \return dtkErrorNullPointer : inBody is null.
//! \return dtkErrorTypeNotsupported : not supported in AP203 version.
DtkErrorStatus stepw_Write3DConstructionGeometry( const Dtk_BodyPtr& inBody );
 
//! \ingroup step_write
//! \brief Writes an axis system of a 3D part, in STEP, it is a construction geometry based on an axis placement.
//! \details Usually used to complement FDT definition.
//! \param[in] inAxis : the axis to be written.
//! \return dtkNoError : the axis has been correctly written.
//! \return dtkErrorUnspecified : part context hasn't been initialized.
//! \return dtkErrorNullPointer : inAxis is null.
//! \return dtkErrorTypeNotsupported : not supported in AP203 version.
DtkErrorStatus stepw_Write3DAxisSystem( const Dtk_AxisSystemPtr& inAxis );
 
//! \ingroup step_write
//! \brief Writes a mesh of a 3D part (3D content of a product).
//! \details Default is mockup mesh. If no mockup is defined, basic triangles are written instead.
//! \warning: correct mapping is with mockup; writing basic triangles of meshes is not efficient.
//! \param[in] inMesh : the mesh to be written.
//! \return dtkNoError : the mesh has been correctly written.
//! \return dtkErrorUnspecified : part context hasn't been initialized.
//! \return dtkErrorNullPointer : inMesh is null.
DtkErrorStatus stepw_Write3DPartMesh( const Dtk_MeshPtr& inMesh );
 
//! \ingroup step_write
//! \brief Writes a mesh of a 3D part (3D content of a product), coming from a body, without writing the body itself.
//! \details The mesh is assumed to be the result of computing tessellation on the body in case of association : its items can be bound with items of the body.
//! \see Write3DPartBodyWithMesh : writes both the body and the mesh.
//! \param[in] inMesh : the mesh to be written.
//! \param[in] inBody : the body it comes from (not written), ignored if null (acts as Write3DPartMesh).
//! \return dtkNoError : the mesh has been correctly written.
//! \return dtkErrorUnspecified : part context hasn't been initialized.
//! \return dtkErrorNullPointer : inMesh is null.
DtkErrorStatus stepw_Write3DPartMeshFromBody( const Dtk_MeshPtr& inMesh, const Dtk_BodyPtr& inBody );
 
//! \ingroup step_write
//! \brief Adds a FDT in the current part context.
//! \details Can be called at any time between stepw_Init3DPart and stepw_End3DPart, writing takes place after the bodies.
//! \param[in] inFDT : the FDT to be written with the 3D part (according to ModeFdt, as semantic and/or graphic).
//! \return dtkNoError : the FDT has been correctly added.
//! \return dtkErrorNotProcessed : inFDT is null.
//! \return dtkErrorLicence : no licence active or stepw_SetModeFdt not called before starting.
DtkErrorStatus stepw_Add3DPartFDT( const Dtk_FdtPtr& inFDT );
 
//! \ingroup step_write
//! \brief Adds a FDT in the current part context, with a predefined graphic presentation.
//! \details Can be called at any time between stepw_Init3DPart and stepw_End3DPart, writing takes place after the bodies.
//! \param[in] inFDT : the FDT to be written as semantic data with the 3D part.
//! \param[in] inFDT : the FDT to be used for graphical presentation with the 3D part.
//! \return dtkNoError : the FDT has been correctly added.
//! \return dtkErrorNotProcessed : inFDT is null.
//! \return dtkErrorLicence : no licence active or stepw_SetModeFdt not called before starting.
DtkErrorStatus stepw_Add3DPartFDT( const Dtk_FdtPtr& inFDT, const Dtk_FdtPtr& inFDTGraf );
 
//! \ingroup step_write
//! \brief Adds a FDT in the current part context, with an element reference (usually the target geometry).
//! \see stepw_CreateReference
//! \param[in] inFDT : the FDT to be written with the 3D part (according to ModeFdt, as semantic and/or graphic).
//! \param[in] inER : the element reference allowing the FDT to target entities (usually geometries).
//! \return dtkNoError : the FDT and its element reference have been correctly added.
//! \return dtkErrorNotProcessed : inFDT is null.
//! \return dtkErrorLicence : no licence active or stepw_SetModeFdt not called before starting.
DtkErrorStatus stepw_Add3DPartFDT( const Dtk_FdtPtr& inFDT, const stepw_ER& inER );
 
 
//! \ingroup step_write
//! \brief  Adds a view ( Dtk_ModelDisplay ) in the current part context.
//! \details Can be called at any time between stepw_Init3DPart and stepw_End3DPar, writing takes place after the bodies.
//! \param[in] inModelDisplay : the view to be written with the 3D Part.
//! \param[in] inMode : 0 no FDT/Annotation is attached to the view (default), 1 all FDT/Annotations are attached to the view.
//! \return dtkNoError : the view has been correctly added.
//! \return dtkErrorNullPointer : inModelDisplay is null.
//! \return dtkErrorLicence : no licence active or stepw_SetModeFdt not called before starting.
Dtk_ErrorStatus stepw_Add3DModelDisplay( const Dtk_ModelDisplayPtr& inModelDisplay, const int inMode );
 
//! \ingroup step_write
//! \brief Adds a view ( Dtk_ModelDisplay ) with a link to a FDT, in the current part context.
//! \details Can be called at any time between stepw_Init3DPart and stepw_End3DPart - writing takes place after the bodies. 
//! \details A same FDT can be used in several views.
//! \warning stepw_Add3dPartFDT call is required, here only the link with the view/model_display is recorded.
//! \remark There is no required order between Add3dPartFDT and Add3dFdtModelDisplay.
//! \param[in] inModelDisplay : the view to be written with the 3D Part.
//! \param[in] inFDT : the FDT to be linked to the view.
//! \return dtkNoError : the view and link have been correctly added.
//! \return dtkErrorNullPointer : inModelDisplay or inFDT is null.
//! \return dtkErrorLicence : no licence active or stepw_SetModeFdt not called before starting.
//! \deprecated Use stepw_Add3DModelDisplay and stepw_AddReference instead.
SetAsDeprecated( "2025.4", "Use stepw_Add3DModelDisplay and stepw_AddReference instead.")
Dtk_ErrorStatus stepw_Add3DFdtModelDisplay( const Dtk_ModelDisplayPtr& inModelDisplay, const Dtk_FdtPtr& inFDT );
 
 
DtkErrorStatus stepw_Write3DPartRoot();
 
//! \ingroup step_write
//! \brief Ends the writing of a product 3D part.
//! \return dtkNoError : context has been correclty closed.
//! \return dtkErrorUserBreak : error in calling sequence.
DtkErrorStatus stepw_End3DPart();
 
//! \ingroup step_write
//! \brief Writes instances detained by a product.
//! \see stepw_EndProduct.
//! \param[in] inID : unique identifier for a product. Must be the same as for stepw_InitProduct.
//! \return dtkNoError : instances have been correctly written.
//! \return dtkErrorUnspecified : error in calling sequence.
DtkErrorStatus stepw_WriteAssemblyInstances( const int inID );  // inID must repeat that of InitProduct.
 
//! \ingroup step_write
//! \brief Ends the writing of a product - calls WriteAssemblyInstances if not yet done.
//! \param[in] inID : unique identifier for a product. Must be the same as for stepw_InitProduct.
//! \return dtkNoError : context has been correclty closed.
//! \return dtkErrorUnspecified : error in calling sequence.
DtkErrorStatus stepw_EndProduct( const int inProductID );
 
 
//! \ingroup step_write
//! \brief Ends the writing of the current STEP file
//! \return dtkNoError : file context has been correctly closed.
DtkErrorStatus stepw_EndFile();
 
 
//Classes to describe element references inside a product or between products.
class stepw_ER //Placeholder for element reference
{
public:
     stepw_ER();
     void* m_pData;
};
 
class stepw_ERP //Placeholder for element reference path
{
public:
     stepw_ERP();
     void* m_pData;
};
 
//! \ingroup step_write
//! \brief Creates a reference to an entity located in the designated Product/Part context, or current context if not specified.
//! \param[in, out] inOutElementReference : object representing the reference, that will be used internally.
//! \param[in] inEntityID : identifier of a Dtk_Entity that will be referenced in current Product/Part.
//! \param[in] inProductID : identifier of the Product in which the entity is located. If equals 0, the current Product/Part context is used.
//! \param[in] inReferenceKind : Optional, character sequence to specify the reason of the reference. Supported sequences are "fdt", "group", "visible", "hidden".
//! "fdt" allows to specify that the target of the reference is a FDT entity (Dtk_Fdt).
//! "group" allows to specify that the target of the reference is a feature (interpreted as a group of geometries) (Dtk_Feature).
//! "visible" allows to specify that the target should be visible in the designated Product/Part context.
//! "hidden" allows to specify that the target should be hidden in the designated Product/Part context.
//! \see stepw_CreateReferenceToFdt
//! \see stepw_CreateReferenceToGroup
//! \return dtkNoError : content of inOutElementReference has been filled.
//! \return dtkErrorUnspecified : content of inOutElementReference has not been filled, allocation issue or unrecognized character sequence in case the reference reason has been specified.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_CreateReference( stepw_ER& inOutElementReference, const int inEntityID, const int inProductID = 0, const char* inReferenceKind = "");
 
//! \ingroup step_write
//! \brief Creates a reference to a whole node (Dtk_Node), located in the designated Product/Part context.
//! \param [in, out] inOutElementReference : object representing the reference, that will be used internally.
//! \param[in] inNodeID : identifier of a Dtk_Node that will be referenced in current Product/Part context.
//! \param[in] inProductID : identifier of the Product in which the entity is located. If equals 0, the current Product/Part context is used.
//! \param[in] inReferenceKind : Optional, character sequence to specify the reason of the reference. Supported sequences are "fdt", "group", "visible", "hidden".
//! "fdt" allows to specify that the target of the reference is a node that contains a FDT (Dtk_Node, Dtk_Fdt).
//! "group" allows to specify that the target of the reference is a node that contains a feature (interpreted as a group of geometries) (Dtk_Node, Dtk_Feature).
//! "visible" allows to specify that the target should be visible in the designated Product/Part context.
//! "hidden" allows to specify that the target should be hidden in the designated Product/Part context.
//! \return dtkNoError : content of inOutElementReference has been filled.
//! \return dtkErrorUnspecified : content of inOutElementReference has not been filled, allocation issue or unrecognized character sequence in case the reference reason has been specified.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_CreateReferenceToNode( stepw_ER& inOutElementReference, const int inNodeID, const int inProductID = 0, const char* inReferenceKind = "");
 
//! \ingroup step_write
//! \brief Registers the previously created element reference in the writer.
//! \param [in] inElementReference : object representing the reference, that will be used internally.
//! \return dtkNoError : content of inElementReference has been filled.
//! \return dtkErrorUnspecified : content of inElementReference is empty.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_AddReference( stepw_ER& inElementReference );
 
//! \ingroup step_write
//! \brief Creates a reference to an entity located in the designated Product/Part context. The reference target is known to be an FDT (Dtk_FDT).
//! \param[in, out] inOutElementReference : object representing the reference, that will be used internally.
//! \param[in] inEntityID : identifier of a Dtk_Entity that will be referenced in current Product/Part (is an FDT).
//! \param[in] inProductID : identifier of the Product in which the entity is located. If equals 0, the current Product/Part context is used.
//! \remark Same as stepw_CreateReference( inOutElementReference, inEntityID, inProductID, "fdt" ).
//! \return dtkNoError : content of inOutElementReference has been filled.
//! \return dtkErrorUnspecified : content of inOutElementReference has not been filled, allocation issue.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_CreateReferenceToFdt( stepw_ER& inOutElementReference, const int inEntityID, const int inProductID );
 
//! \ingroup step_write
//! \brief Creates a reference to an entity located in the designated Product/Part context. The reference target is known to be a feature (Dtk_Feature) (interpreted as a group of geometries).
//! \param[in, out] inOutElementReference : object representing the reference, that will be used internally.
//! \param[in] inEntityID : identifier of a Dtk_Entity that will be referenced in current Product/Part (is a feature).
//! \param[in] inProductID : identifier of the Product in which the entity is located. If equals 0, the current Product/Part context is used.
//! \remark Same as stepw_CreateReference( inOutElementReference, inEntityID, inProductID, "group" ).
//! \return dtkNoError : content of inOutElementReference has been filled.
//! \return dtkErrorUnspecified : content of inOutElementReference has not been filled, allocation issue.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_CreateReferenceToGroup( stepw_ER& inOutElementReference, const int inEntityID, const int inProductID );
 
//! \ingroup step_write
//! \brief Initializes a path for the element reference, identifying the sequence of instances to pass through.
//!\details When in the context of an assembly with more than one depth level, to designates the instance of a part/product located at a deeper level, there is a need to identify all of the part/product instances we pass through.
//! \param[in, out] inOutElementReferencePath : object representing the reference path, that will be used internally.
//! \see stepw_AddInstanceWithInfo
//! \return dtkNoError : inOutElementReferencePath has been initialized.
//! \return dtkErrorUnspecified : content of inOutElementReferencePath has not been initialized, allocation issue.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_CreateInstancePath( stepw_ERP& inOutElementReferencePath );
 
//! \ingroup step_write
//! \brief Appends an instance identifier to the element reference path. The instance identifier is provided by this library.
//!\details When in the context of an assembly with more than one depth level, to designates the instance of a part/product located at a deeper level, there is a need to identify all of the part/product instances we pass through.
//! \param[in, out] inOutElementReferencePath : object representing the reference path, that will be used internally.
//! \param[in] inInstanceID : identifier of an instance to append to the element reference path.
//! \see stepw_AddInstanceWithInfo
//! \return dtkNoError : the instance identifier has been appended to the element reference path.
//! \return dtkErrorUnspecified : content of inOutElementReferencePath is empty or instance identifier is invalid (does not identify a previously registered instance).
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_AddInstanceToPath( stepw_ERP& inOutElementReferencePath, const int inInstanceID );
 
//! \ingroup step_write
//! \brief Define the whole instance identifier sequence of the element reference path.
//!\details When in the context of an assembly with more than one depth level, to designates the instance of a part/product located at a deeper level, there is a need to identify all of the part/product instances we pass through.
//! \param[in, out] inOutElementReferencePath : object representing the reference path, that will be used internally.
//! \param[in] inInstancePath : sequence of instance identifiers to define for the element reference path.
//! \return dtkNoError : the sequence of instance identifiers has been set for the element reference path.
//! \return dtkErrorUnspecified : the sequence of instance identifiers is invalid (does not identify previously registered instances).
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
Dtk_ErrorStatus stepw_DefineInstancePath( stepw_ERP& inOutElementReferencePath, const Dtk_tab<Dtk_ID>& inInstancePath, const bool unused = false );
 
//! \ingroup step_write
//! \brief Assigns the element reference path to the element reference.
//! \param[in, out] inOutElementReference : the element reference to which the path will be assigned.
//! \param[in] inElementReferencePath : the path to assign to the element reference.
//! \return dtkNoError : the path has been assigned.
//! \return dtkErrorUnspecified : either inOutElementReference or inElementReferencePath content is empty.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_SetReferencePath( stepw_ER& inOutElementReference, stepw_ERP& inElementReferencePath );
 
//! \ingroup step_write
//! \brief Assigns information on an instance in multi-level assembly context.
//! \details The first identifier of the route designating the instance allows to deduce in which assembly context the instance will hold the information.
//! \details This produces the writing of a CONTEXT_DEPENDENT_OVERRIDING_STYLED_ITEM.
//! \param[in] inElementReferencePath : the instance route to designate the instance in the assembly.
//! \param[in] inOverrideInfo : the information to apply to this instance. Only color and blanked status are taken into account.
//! \see stepw_CreateInstancePath
//! \return dtkNoError : the override information has been correctly assigned to the instance.
//! \return dtkErrorUnspecified : inOutElementReference content is empty.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
Dtk_ErrorStatus stepw_AddOverrideInstanceInfo( stepw_ERP& inElementReferencePath, Dtk_InfoPtr& inOverrideInfo );
 
//! \ingroup step_write
//! \brief Declares the product as having an ANCHOR section. If the designated product is already declared as such, sets its user-defined identifier.
//! \details Having an ANCHOR section allows the product to declare entities that can be referenced from outside of the product file, in cases where this product is written in a separated file.
//! \param[in] inProductID : identifier of the product to declare.
//! \param[in] inUserID : identifier the user wants to provide to the product, to be able to retrieve it later.
//! \see stepw_AnchorProductID
//! \return dtkNoError : the product is declared as having an ANCHOR section.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
DtkErrorStatus stepw_SetAnchorProduct( const int inProductID, const int inUserID );
 
//! \ingroup step_write
//! \brief Finds the product having an ANCHOR section, by user identifier.
//! \param[in] inUserID : identifier the user previously provided to identify the product.
//! \see stepw_SetAnchorProduct
//! \return 0 : the product hasn't been found.
//! \return positive value : the found product corresponding identifier (non-user defined)
int stepw_AnchorProductID( const int inUserID );
 
//! \ingroup step_write
//! \brief Registers an entity in the ANCHOR section, with an assigned GUID (optional).
//! \details Entities declared in the ANCHOR section can be referenced from outside of the product file, in cases where this product is written in a separated file.
//! \details If the designated product is not yet declared as having an ANCHOR section, it calls stepw_SetAnchorProduct.
//! \see stepw_SetAnchorProduct
//! \param[in] inEntityID : identifier of the entity to declare in the ANCHOR section.
//! \param[in] inProductID : identifier of the product where to declare entities in the ANCHOR section.
//! \param[in] inGUID : the GUID to assign to the entity.
//! \return dtkNoError : the entity has been correctly declared in the ANCHOR section.
//! \return dtkErrorUnspecified : the product identifier does not identify a product in the current file.
//! \return dtkErrorNotProcessed : the entity is already registered with a different GUID.
//! \return dtkErrorOpenFiles : STEPWriter is not initialized.
Dtk_ErrorStatus stepw_AddAnchorItem( const int inEntityID, const int inProductID, const Dtk_string& inGUID );
 
 
 
#endif