///////////////////////////////////////////////////////////////////////////////
// Copyright (C) 2002-2025, Open Design Alliance (the "Alliance").
// All rights reserved.
//
// This software and its documentation and related materials are owned by
// the Alliance. The software may only be incorporated into application
// programs owned by members of the Alliance, subject to a signed
// Membership Agreement and Supplemental Software License Agreement with the
// Alliance. The structure and organization of this software are the valuable
// trade secrets of the Alliance and its suppliers. The software is also
// protected by copyright law and international treaty provisions. Application
// programs incorporating this software must include the following statement
// with their copyright notices:
//
// This application incorporates Open Design Alliance software pursuant to a license
// agreement with Open Design Alliance.
// Open Design Alliance Copyright (C) 2002-2025 by Open Design Alliance.
// All rights reserved.
//
// By use of this software, its documentation or related materials, you
// acknowledge and accept the above terms.
///////////////////////////////////////////////////////////////////////////////
#ifndef _ODTV_DATABASE_H_INCLUDED_
#define _ODTV_DATABASE_H_INCLUDED_
#include "Tv.h"
#include "TvModel.h"
#include "TvBlock.h"
#include "TvLinetype.h"
#include "TvLayer.h"
#include "TvRasterImage.h"
#include "TvVisualStyle.h"
#include "TvGsViewBackground.h"
#include "TvIObject.h"
#include "TvGsDevice.h"
#include "TvExport.h"
#include "TvStatistics.h"
#include "TvCommonDataAccessTree.h"
#include "TvAnimation.h"
#include "TvRtRenderSettings.h"
class OdTvBaseImportParams;
/** \details
Class for storing compression parameters.
*/
struct ODTV_EXPORT OdTvVSFExportOptions
{
/** \details
Defines the compression type used for the vertices in different geometry data such as NURBS, polylines, shells, etc.
*/
enum Compression
{
/** Compression is disabled. */
kNoCompression,
/** Use floats instead of doubles. */
kFloat,
/** Use 4-byte integers instead of doubles. */
kInt32,
/** Use 2-byte integers instead of doubles. */
kInt16,
};
/** \details
Defines the compression type for normals.
*/
enum NormalsCompression
{
/** Compression is disabled. */
kDisabledCompression,
/** Use 2 floats instead of 3 doubles. */
kTwoFloats,
/** Use 2 integers (4 bytes each) instead of 3 doubles. */
kTwoInt32,
/** Use one 2-byte integer instead of 3 doubles. */
kOneInt16,
};
/** \details
This interface represents the export overwriter.
*/
class ODTV_EXPORT OdTvVSFExportOverwriter
{
public:
/** \details
Overwrites an RCS file name.
\param originalName [in] Original RCS file name.
\returns The overwritten RCS file name.
*/
virtual OdString overwriteRcsFileName( const OdString& originalName ) = 0;
};
/** \details
Structure for Gs Cache Storing parameters.
*/
struct OdTvGsCacheStoringOptions
{
/** Specifies whether gs cache should be stored or not */
bool bStoreGsCache = false;
/** Specifies whether gs cache storing should support partial load mode or not */
bool bSupportPartialLoad = true;
/** Specifies whether gs cache storing should use compression or not */
bool bEnableStreamCompression = true;
/** Specifies whether Visualze objects should be substituted by stub if they have stored Gs cache or not */
bool bSubstituteCachedObjects = true;
/** Specifies whether Visualze objects inside the blocks have to be always substituted (regardless stored GS cache) or not */
bool bSubstituteBlockContent = true;
};
/** \details
Default constructor for the OdTvVSFExportOptions class. Creates an object
that specifies that no compression is used for vertices and no compression is used for normals.
*/
OdTvVSFExportOptions()
:compression(kNoCompression), normalsCompression(kDisabledCompression), m_IgnoreFaceNormals(false), pOverwriter( NULL )
{
}
/** \details
Constructor for the OdTvVSFExportOptions class. Creates an object with the specified compression parameters.
\param compression [in] Compression options for vertices.
\param normalsCompression [in] Compression options for normals.
*/
OdTvVSFExportOptions(Compression compression, NormalsCompression normalsCompression)
:compression(compression), normalsCompression(normalsCompression), m_IgnoreFaceNormals(false), pOverwriter( NULL )
{
}
/** Represents compression for vertices */
Compression compression;
/** Represents compression for normal vectors */
NormalsCompression normalsCompression;
/** Indicates that it is not need to write normals in the file */
bool m_IgnoreFaceNormals;
/** Represents export overwriter */
OdTvVSFExportOverwriter* pOverwriter;
/** Specifies gs cache storing parameters */
OdTvGsCacheStoringOptions gsCacheStoringOptions;
};
/** \details
Struct for storing VSFX read parameters.
\sa
*/
struct ODTV_EXPORT OdTvVSFXReadOptions
{
/** \details
Defines progressive mesh loading mode.
*/
enum ProgressiveMeshMode
{
/** Normal mode - all data loaded. */
kNormalMode,
/** Partial mode - LOD information kept in the stream. */
kPartialMode,
/** Partial mode - LOD information kept in the stream, but all information is loaded while switching LOD. */
kFastPartialMode
};
/** \details
Structure for Gs Cache Loading parameters.
*/
struct OdTvGsCacheLoadingOptions
{
/** Specifies whether gs cache should be loaded or not */
bool bLoadGsCache = false;
/** Specifies whether gs cache loading should use partial load mode or not */
bool bEnablePartialMode = true;
};
/** \details
Default constructor for the OdTvVSFXReadOptions struct. Creates an object
that specifies that progressive meshes will be loaded in normal mode.
*/
OdTvVSFXReadOptions()
:progressiveMeshMode( kNormalMode )
{}
/** \details
Constructor for the OdTvVSFXReadOptions struct. Creates an object with specified parameters.
\param pmMode [in] Progressive mesh loading mode.
*/
OdTvVSFXReadOptions( ProgressiveMeshMode pmMode )
:progressiveMeshMode( pmMode )
{}
/** Represents progressive mesh loading mode. */
ProgressiveMeshMode progressiveMeshMode;
/** Specifies gs cache loading parameters */
OdTvGsCacheLoadingOptions gsCacheLoadingOptions;
};
/** \details
An abstract class that implements the interface for interaction with a Visualize SDK database.
\sa
*/
class ODTV_EXPORT OdTvDatabase : public OdTvIObjectWithXdata
{
public:
/** \details
Defines the types of preferable visual styles
*/
enum PreferableVisualStylesType
{
kWireframe = 0, // Standard display.
kHiddenLine = 1, // Hidden lines display.
kShaded = 2, // Shaded display.
kShadedWithTessellation = 3, // Shaded display with tessellation wireframe overlay.
kShadedWithIsolines = 4, // Shaded display with isolines overlay.
kCustom = 5 // Custom preferable visual style. By default 2D Wireframe.
};
/** \details
Creates a new model for the database.
\param name [in] A model name.
\param type [in] A model type.
\param bNeedSaveInFile [in] A flag that indicates whether the model should be saved in a file.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The identifier of the created model.
\remarks
If the rc parameter value is not NULL and the model is created successfully,
the rc parameter accepts the tvOk value; otherwise it contains an error code.
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
Also there are three forbidden names, "*Model_Space", "*Paper_Space", and "*Paper_Space0", which can not be used as model names.
\sa
*/
virtual OdTvModelId createModel(const OdString& name, OdTvModel::Type type = OdTvModel::kMain, bool bNeedSaveInFile = true, OdTvResult* rc = NULL) = 0;
/** \details
Creates a new model reference for the database.
\param name [in] A model name.
\param databasePath [in] A path to the reference database.
\param modelName [in] A name of referenced model.
\param type [in] A model type.
\param bForcePartialMode [in] A flag that specifies whether referenced database should be forced to use partial mode.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The identifier of the created model.
\remarks
By default, referenced database will be opened in the partial mode only if current database works in this mode. Parameter bForcePartialMode can change this behavior.
*/
virtual OdTvModelId createModelReference( const OdString& name, const OdString& databasePath, const OdString& modelName, OdTvModel::Type type = OdTvModel::kMain, bool bForcePartialMode = false, OdTvResult* rc = NULL ) = 0;
/** \details
Removes the model with the specified identifier from the database.
\param id [in] An identifier of the model to be removed.
\returns A value of the type that contains the result of the remove operation.
\remarks
If the model is successfully removed from the database, the method returns the tvOk value; otherwise it returns an appropriate
error code.
\sa
*/
virtual OdTvResult removeModel(const OdTvModelId& id) = 0;
/** \details
Removes all models from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If models are successfully removed, the method returns the tvOk value; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearModels() = 0;
/** \details
Searches for a model with the specified name.
\param name [in] A name of the model that should be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found model. If the model is not found, returns a null-value identifier.
\remarks
If the rc parameter is not NULL and the model with the specified name is found, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
Another way to understand whether the model was found is to call the isNull() method of the returned
object. If this method returns false, the model was found.
*/
virtual OdTvModelId findModel(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator object for getting access to models that the database contains.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the model's iterator object. If the iterator can not be retrieved, the returned smart pointer is NULL.
\remarks
If the rc parameter is not NULL and the method returns a valid smart pointer to a valid iterator; the rc parameter
accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdTvModelsIteratorPtr getModelsIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a new block in the database.
\param name [in] A name of the new block.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the newly created block.
\remarks
If the new block is successfully created, the method isNull() of the returned identifier returns false.
If the rc parameter is not null and the block is created, the rc parameter accepts the tvOk value; otherwise it contains an
appropriate error code.
The new block name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
Also there are three forbidden names, "*Model_Space", "*Paper_Space", "*Paper_Space0", which can not be used as a block name.
\sa
*/
virtual OdTvBlockId createBlock(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Removes a block object with the specified identifier from the database.
\param id [in] An identifier of the block that should be removed.
\returns A value of the type that contains the result of the operation.
\remarks
If the block is successfully removed, the method returns the tvOk value; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeBlock(const OdTvBlockId& id) = 0;
/** \details
Removes all blocks from the database.
\returns A value of the type that contains the result of the operation.
\remarks
If all blocks are removed from the database, the method returns the tvOk value; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearBlocks() = 0;
/** \details
Finds a block by name.
\param name [in] A name of a block that should be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns The identifier of the found block. If the block is not found, the method returns a null-value identifier.
\remarks
If the rc parameter is not null and the block is found, the rc parameter accepts the tvOk value; otherwise it contains
an appropriate error code.
Another way to understand whether the block was found is to call the isNull() method of the returned identifier.
If it returns false, the block was found. Otherwise the isNull() method returns true.
*/
virtual OdTvBlockId findBlock(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator for accessing database blocks.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator object.
\remarks
If the rc parameter is not null and the iterator object is successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
Another way to check whether a correct iterator was returned is to check the returned smart pointer for the NULL value.
If it is not NULL, the iterator object returned by the method is correct.
*/
virtual OdTvBlocksIteratorPtr getBlocksIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a new linetype object in the database.
\param name [in] A linetype name as a String value up to 255 characters long.
\param elements [in] An array of the linetype pattern elements.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created linetype object.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
Also there are three forbidden names, "Continuous", "ByBlock", "ByLayer", which can not be used as the linetype name.
If the rc parameter is not NULL and a new linetype object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of linetype creation by calling the isNull() method of the returned identifier.
If this method returns false, the linetype was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvLinetypeId createLinetype(const OdString& name, const OdTvLinetypeElementArray& elements, OdTvResult* rc = NULL) = 0;
/** \details
Creates a new linetype object in the database.
\param name [in] A linetype name as a String value up to 255 characters long.
\param nElements [in] A number of linetype pattern elements.
\param elements [in] A smart pointer that represents the array of the linetype pattern elements.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created linetype object.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
Also there are three forbidden names, "Continuous", "ByBlock", "ByLayer", which can not be used as the linetype name.
If the rc parameter is not NULL and a new linetype object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the linetype creation by calling the isNull() method of the returned identifier.
If this method returns false, the linetype was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvLinetypeId createLinetype(const OdString& name, OdInt32 nElements, const OdTvLinetypeElementPtr* elements, OdTvResult* rc = NULL) = 0;
/** \details
Removes a linetype object with the specified identifier from the database.
\param id [in] An identifier of the linetype object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
\remarks
If the specified linetype object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeLinetype(const OdTvLinetypeId& id) = 0;
/** \details
Removes all linetype objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all linetype objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearLinetypes() = 0;
/** \details
Searches for a linetype object with a specified name in the database.
\param name [in] A name of the linetype object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found linetype object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the linetype object was found; otherwise it contains an
appropriate error code.
\sa
*/
virtual OdTvLinetypeId findLinetype(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns an iterator object to get sequential access to linetype objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine), you can check whether the correct iterator is returned by the method
by checking whether the returned smart pointer is not NULL.
\sa
*/
virtual OdTvLinetypesIteratorPtr getLinetypesIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a new layer object in the database.
\param name [in] A new layer name represented with a string value up to 255 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created layer if the creation is successful, or returns a null identifier.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
Also there is a forbidden name, "0", which can not be used as the layer name.
If the rc parameter is not NULL and the new layer object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of layer creation by calling the isNull() method of the returned identifier.
If this method returns false, the layer was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvLayerId createLayer(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Removes a layer object with the specified identifier from the database.
\param id [in] An identifier of the layer object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
If the specified layer object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeLayer(const OdTvLayerId& id) = 0;
/** \details
Removes all layer objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all layer objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearLayers() = 0;
/** \details
Searches for a layer object with a specified name in the database.
\param name [in] A name of the layer object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found layer object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the layer object was found; otherwise it contains an
appropriate error code.
*/
virtual OdTvLayerId findLayer(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to layer objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine), you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvLayersIteratorPtr getLayersIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a new text style object in the database.
\param name [in] A new text style name represented with a string value up to 255 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created text style if the creation is successful, or returns a null identifier.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
Also there is a forbidden name, "Standard", which can not be used as the text style name.
If the rc parameter is not NULL and a new text style is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of text style creation by calling the isNull() method of the returned identifier.
If this method returns false, the text style was successfully created. Otherwise the isNull() method returns true.
The created text style uses a built-in font unless you specify another font for it.
\sa
*/
virtual OdTvTextStyleId createTextStyle(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Removes the text style object with the specified identifier from the database.
\param id [in] An identifier of the text style object that should be deleted.
\returns A value of the link OdTvResult, OdTvResult> type that contains the result of the remove operation.
\remarks
If the specified text style is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeTextStyle(const OdTvTextStyleId& id) = 0;
/** \details
Removes all text styles from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all text styles are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearTextStyles() = 0;
/** \details
Searches for a text style with a specified name in the database.
\param name [in] A name of the text style object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found text style if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the text style object was found; otherwise it contains an
appropriate error code.
*/
virtual OdTvTextStyleId findTextStyle(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to text styles in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine), you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvTextStylesIteratorPtr getTextStylesIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a new material object in the database.
\param name [in] A new material object name represented with a string value up to 255 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created material object if the creation is successful, or returns a null identifier.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
Also there are forbidden names, "Global", "ByBlock", "ByLayer", which can not be used as the material name.
If the rc parameter is not NULL and the new material object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of material object creation by calling the isNull() method of the returned identifier.
If this method returns false, the material object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvMaterialId createMaterial(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Removes the material object with the specified identifier from the database.
\param id [in] An identifier of the material object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
\remarks
If the specified material object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeMaterial(const OdTvMaterialId& id) = 0;
/** \details
Removes all material objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all material objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearMaterials() = 0;
/** \details
Searches for a material object with a specified name in the database.
\param name [in] A name of the material object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found material object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the material object was found; otherwise it contains an
appropriate error code.
*/
virtual OdTvMaterialId findMaterial(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Searches for a material object using comparator.
\param pCmp [in] A pointer to the material comparator.
\param name [in] A name of the material object to be found (optional).
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns
An identifier of the found material object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the material object was found; otherwise it contains an
appropriate error code.
If the name parameter is specified, method tries to find material by the given name. If material is not found by its name, the method then uses comparator for this material: if it returns true, the found material is returned. Otherwise all other
database materials are processed using the comparator.
*/
virtual OdTvMaterialId findMaterial( const OdTvMaterialComparator* pCmp, const OdString& name = OdString::kEmpty, OdTvResult* rc = NULL ) = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to material objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvMaterialsIteratorPtr getMaterialsIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a new raster image object in the database.
\param name [in] A new raster image name represented with a string value up to 255 characters long.
\param pathName [in] A path of the image source file.
\param bLoad [in] A flag value that indicates whether the raster image should be immediately loaded.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created raster image object if the creation is successful, or returns a null identifier.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
If the rc parameter is not NULL and a new raster image object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of raster image object creation by calling the isNull() method of the returned identifier.
If this method returns false, the raster image object was successfully created. Otherwise the isNull() method returns true.
\sa
Working with Source File-Based Images
*/
virtual OdTvRasterImageId createRasterImage(const OdString& name, const OdString& pathName, bool bLoad = false, OdTvResult* rc = NULL) = 0;
/** \details
Creates a new raster image object in the database.
\param name [in] A new raster image name represented with a string value up to 255 characters long.
\param format [in] A format of the raster image (describes how data in the data array is packed).
\param width [in] A width of the raster image in pixels.
\param height [in] A height of the raster image in pixels.
\param data [in] A byte array that describes the color of each image pixel. This byte array is packed according to the image format.
\param iAlignment [in] A byte alignment value.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created raster image object if the creation is successful, or returns a null identifier.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
If the rc parameter is not NULL and a new raster image object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of raster image object creation by calling the isNull() method of the returned identifier.
If this method returns false, the raster image object was successfully created. Otherwise the isNull() method returns true.
\sa
Working with Binary Images
*/
virtual OdTvRasterImageId createRasterImage(const OdString& name, OdTvRasterImage::Format format, OdUInt32 width, OdUInt32 height, const OdUInt8* data, OdUInt32 iAlignment = 4, OdTvResult* rc = NULL) = 0;
/** \details
Creates a palette-based binary raster image object and returns the appropriate ID.
\param name [in] A new raster image name represented with a string value up to 255 characters long.
\param paletteformat [in] A description of how the color data in the palette data array is packed.
\param paletteSize [in] The number of colors in the palette.
\param paletteData [in] An array of bytes, packed according to the image format, that describes the color palette.
\param bpi [in] A description of how indexes in the data array are packed.
\param width [in] A width of the raster image in pixels.
\param height [in] A height of the raster image in pixels.
\param data [in] An array of bytes, packed according to the image format, that describes the index in the palette for each pixel in the image.
\param iAlignment [in] A byte alignment value.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created raster image object if the creation is successful, or returns a null identifier.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
If the rc parameter is not NULL and a new raster image object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of raster image object creation by calling the isNull() method of the returned identifier.
If this method returns false, the raster image object was successfully created. Otherwise the isNull() method returns true.
\sa
Working with Palette-Based Images
*/
virtual OdTvRasterImageId createRasterImage(const OdString& name, OdTvRasterImage::Format paletteformat, OdUInt32 paletteSize, OdUInt8* paletteData,
OdTvRasterImage::BitPerIndex bpi, OdUInt32 width, OdUInt32 height, const OdUInt8* data,
OdUInt32 iAlignment = 4, OdTvResult* rc = NULL) = 0;
/** \details
Creates a monochrome raster image object and returns the appropriate ID.
\param name [in] A new raster image name represented with a string value up to 255 characters long.
\param width [in] A width of the raster image in pixels.
\param height [in] A height of the raster image in pixels.
\param data [in] An array of bytes that describes the presence of the main color in each pixel of the image.
\param bInverted [in] A background flag value. If the flag is equal to true, the background color is used as the main color.
\param iAlignment [in] A byte alignment value.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created raster image object if the creation is successful, or returns a null identifier.
\remarks
The name is an arbitrary non-empty string that can contain letters, digits, blank spaces,
underscores, and some special characters, but cannot contain inadmissible letters
("<", ">", "\", "/", ":", ";", "?", ",", "*", "|", "=", "'", quotation marks and some special characters created with Unicode fonts).
If the rc parameter is not NULL and a new raster image object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of raster image object creation by calling the isNull() method of the returned identifier.
If this method returns false, the raster image object was successfully created. Otherwise the isNull() method returns true.
\sa
Working with Monochrome Images
*/
virtual OdTvRasterImageId createRasterImage(const OdString& name, OdUInt32 width, OdUInt32 height, const OdUInt8* data,
bool bInverted = false, OdUInt32 iAlignment = 4, OdTvResult* rc = NULL) = 0;
/** \details
Removes the raster image object with the specified identifier from the database.
\param id [in] An identifier of the raster image object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
\remarks
If the specified raster image object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult removeRasterImage(const OdTvRasterImageId& id) = 0;
/** \details
Removes all raster image objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all raster image objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult clearRasterImages() = 0;
/** \details
Searches for a raster image object with a specified name in the database.
\param name [in] A name of the raster image object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found raster image object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the raster image object was found; otherwise it contains an
appropriate error code.
*/
virtual OdTvRasterImageId findRasterImage(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to raster image objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvRasterImagesIteratorPtr getRasterImagesIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a new device object in the database.
\param name [in] A device name represented with a string value up to 2049 characters long.
\param wnd_handle [in] An operating system window handle.
\param wndRect [in] A window rectangle associated with the device.
\param device [in] A device type name (GLES2, OpenGL etc).
\param bAllowShare [in] Flag indicates that it is allowed to share data between different devices if it is possible.
\param strVectorizerName [in] A path to the device module (only for when the device parameter is equal to the kCustom value).
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created device object if the creation is successful, or returns a null identifier.
\remarks
If the rc parameter is not NULL and a new device object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of device object creation by calling the isNull() method of the returned identifier.
If this method returns false, the device object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvGsDeviceId createDevice(const OdString& name, OSWindowHandle wnd_handle, const OdTvDCRect &wndRect, OdTvGsDevice::Name device, bool bAllowShare = true, OdString* strVectorizerName = 0, OdTvResult* rc = NULL) = 0;
#ifdef __linux__
/** \details
Creates a new device object in the database.
\param name [in] A device name represented with a string value up to 2049 characters long.
\param wnd_handle [in] An operating system window handle.
\param xdisp_handle [in] An operating system display handle.
\param wndRect [in] A window rectangle associated with the device.
\param device [in] A device type name (GLES2, OpenGL, etc.).
\param bAllowShare [in] Flag indicates that it is allowed to share data between different devices if it is possible.
\param strVectorizerName [in] A path to the device module (only for when the device parameter is equal to the kCustom value).
\param rc [out] A pointer to a value of type that contains the result of the creation.
\returns An identifier of the created device object if the creation is successful, or returns a null identifier.
\remarks
If the rc parameter is not NULL and a new device object is successfully created, the rc parameter accepts the tvOk value;
otherwise, it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of device object creation by calling the isNull() method of the returned identifier.
If this method returns false, the device object was successfully created. Otherwise, the isNull() method returns true.
\sa
*/
virtual OdTvGsDeviceId createDevice(const OdString& name, OSWindowHandle wnd_handle, void* xdisp_handle, const OdTvDCRect &wndRect, OdTvGsDevice::Name device, bool bAllowShare = true, OdString* strVectorizerName = 0, OdTvResult* rc = NULL) = 0;
#endif // __linux__
/** \details
Creates a new device object in the database.
\param name [in] A device name represented with a string value up to 2049 characters long.
\param wnd_context [in] An operating system window GL context.
\param wndRect [in] A window rectangle associated with the device.
\param device [in] A device type name (GLES2, OpenGL etc).
\param bAllowShare [in] Flag indicates that it is allowed to share data between different devices if it is possible.
\param strVectorizerName [in] A path to the device module (only for when the device parameter is equal to the kCustom value).
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created device object if the creation is successful, or returns a null identifier.
\remarks
If the rc parameter is not NULL and a new device object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of device object creation by calling the isNull() method of the returned identifier.
If this method returns false, the device object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvGsDeviceId createDeviceWithContext(const OdString& name, OSWindowGLContext wnd_context, const OdTvDCRect &wndRect, OdTvGsDevice::Name device, bool bAllowShare = true, OdString* strVectorizerName = 0, OdTvResult* rc = NULL) = 0;
#ifdef ODA_WINDOWS
/** \details
Creates a new device object in the database.
\param name [in] A device name represented with a string value up to 2049 characters long.
\param HDC [in] A Windows device context.
\param wndRect [in] A window rectangle associated with the device.
\param device [in] A device type name (GLES2, OpenGL etc).
\param bAllowShare [in] Flag indicates that it is allowed to share data between different devices if it is possible.
\param strVectorizerName [in] A path to the device module (only for when the device parameter is equal to the kCustom value).
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created device object if the creation is successful, or returns a null identifier.
\remarks
If the rc parameter is not NULL and a new device object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of device object creation by calling the isNull() method of the returned identifier.
If this method returns false, the device object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvGsDeviceId createDeviceWithHDC(const OdString& name, void* HDC, const OdTvDCRect& wndRect, OdTvGsDevice::Name device, bool bAllowShare = true, OdString* strVectorizerName = 0, OdTvResult* rc = NULL) = 0;
#endif // ODA_WINDOWS
/** \details
Creates a new "non-setup" device object in the database. The created device does not have defined settings such as window handle, window rectangle, device type name, etc.
\param name [in] A device name represented with a string value up to 2049 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created device object if the creation is successful, or returns a null identifier.
\remarks
The "non-setup" device can only create, add, insert, and erase views. All other methods called from such a device return an error.
If the rc parameter is not NULL and a new device object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of device object creation by calling the isNull() method of the returned identifier.
If this method returns false, the device object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvGsDeviceId createDevice(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Creates a bitmap device object and returns the appropriate ID.
\param name [in] A device name represented with a string value up to 2049 characters long.
\param x [in] An output image X-dimension.
\param y [in] An output image Y-dimension.
\param device [in] A device name (GLES2, OpenGL, etc.)
\param bAllowShare [in] Flag indicates that it is allowed to share data between different devices if it is possible.
\param strVectorizerName [in] A path to the device module (should be passed only if the value of the device parameter is equal to kCustom).
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created device object if the creation is successful, or returns a null identifier.
\remarks
If the rc parameter is not NULL and a new device object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of device object creation by calling the isNull() method of the returned identifier.
If this method returns false, the device object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvGsDeviceId createBitmapDevice(const OdString& name, long x, long y, OdTvGsDevice::Name device, bool bAllowShare = true, OdString* strVectorizerName = 0, OdTvResult* rc = NULL) = 0;
/** \details
Creates a "non-setup" bitmap device object and returns the appropriate ID.
\param name [in] A device name represented with a string value up to 2049 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created device object if the creation is successful, or returns a null identifier.
\remarks
A "non-setup" bitmap device can only create, add, insert and erase views. All other methods for the device object return an error.
If the rc parameter is not NULL and a new device object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of device object creation by calling the isNull() method of the returned identifier.
If this method returns false, the device object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvGsDeviceId createBitmapDevice(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Removes a device object with the specified identifier from the database.
\param id [in] An identifier of the device object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
If the specified device object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeDevice(const OdTvGsDeviceId& id) = 0;
/** \details
Removes all device objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all device objects is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearDevices() = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to device objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvDevicesIteratorPtr getDevicesIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a visual style object as a copy of the given visual style object and returns the appropriate ID.
\param name [in] A visual style name as a String value up to 2049 characters long.
\param vsId [in] A visual style object to copy from, represented with its identifier.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created visual style object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new visual style object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the visual style object creation by calling the isNull() method of the returned identifier.
If this method returns false, the visual style object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvVisualStyleId createVisualStyle(const OdString& name, const OdTvVisualStyleId& vsId, OdTvResult* rc = NULL) = 0;
/** \details
Creates a visual style object as a default visual style object and returns the appropriate ID.
\param name [in] A visual style name as a String value up to 2049 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created visual style object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new visual style object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the visual style object creation by calling the isNull() method of the returned identifier.
If this method returns false, the visual style object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvVisualStyleId createVisualStyle(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Removes a visual style object with the specified identifier from the database.
\param id [in] An identifier of the visual style object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
If the specified visual style object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeVisualStyle(const OdTvVisualStyleId& id) = 0;
/** \details
Removes all visual style objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all visual style objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearVisualStyles() = 0;
/** \details
Searches for a visual style object with a specified name in the database.
\param name [in] A name of the visual style object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found visual style object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the visual style object was found; otherwise it contains an
appropriate error code.
\sa
*/
virtual OdTvVisualStyleId findVisualStyle(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to visual style objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
\sa
*/
virtual OdTvVisualStylesIteratorPtr getVisualStylesIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a view background object and returns the appropriate ID.
\param name [in] A view background name as a String value up to 2049 characters long.
\param bgType [in] A view background type.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created view background object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new view background object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the view background object creation by calling the isNull() method of the returned identifier.
If this method returns false, the view background object was successfully created. Otherwise the isNull() method returns true.
\sa
*/
virtual OdTvGsViewBackgroundId createBackground(const OdString& name, OdTvGsViewBackgroundId::BackgroundTypes bgType, OdTvResult* rc = NULL) = 0;
/** \details
Removes a view background object with the specified identifier from the database.
\param id [in] An identifier of the view background object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
If the specified view background object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult removeBackground(const OdTvGsViewBackgroundId& id) = 0;
/** \details
Removes all view backgrounds objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all view backgrounds objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
\sa
*/
virtual OdTvResult clearBackgrounds() = 0;
/** \details
Searches for a view background object with a specified name in the database.
\param name [in] A name of the view background object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found view background object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the view background object was found; otherwise it contains an
appropriate error code.
*/
virtual OdTvGsViewBackgroundId findBackground(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to view background objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvGsViewBackgroundsIteratorPtr getBackgroundsIterator(OdTvResult* rc = NULL) = 0;
/** \details
Creates a highlight style object as a default highlight style object and returns the appropriate ID.
\param name [in] A highlight style name as a String value up to 2049 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created highlight style object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new highlight style object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the highlight style object creation by calling the isNull() method of the returned identifier.
If this method returns false, the highlight style object was successfully created. Otherwise the isNull() method returns true.
*/
virtual OdTvHighlightStyleId createHighlightStyle(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Creates a highlight style object as a copy of the given highlight style object and returns the appropriate ID.
\param name [in] A highlight style name as a String value up to 2049 characters long.
\param highlightStyleId [in] A highlight style object to copy from, represented with its identifier.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created highlight style object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new highlight style object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the highlight style object creation by calling the isNull() method of the returned identifier.
If this method returns false, the highlight style object was successfully created. Otherwise the isNull() method returns true.
*/
virtual OdTvHighlightStyleId createHighlightStyle(const OdString& name, const OdTvHighlightStyleId& highlightStyleId, OdTvResult* rc = NULL) = 0;
/** \details
Removes a highlight style object with the specified identifier from the database.
\param id [in] An identifier of the highlight style object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
If the specified highlight style object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult removeHighlightStyle(const OdTvHighlightStyleId& id) = 0;
/** \details
Removes all highlight style objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all highlight style objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult clearHighlightStyles() = 0;
/** \details
Searches for a highlight style object with a specified name in the database.
\param name [in] A name of the highlight style object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found highlight style object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the highlight style object was found; otherwise it contains an
appropriate error code.
*/
virtual OdTvHighlightStyleId findHighlightStyle(const OdString& name, OdTvResult* rc = NULL) = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to highlight style objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvHighlightStylesIteratorPtr getHighlightStylesIterator(OdTvResult* rc = NULL) = 0;
/** \details
Returns the version of the VSF file from which this database was read.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The version of the VSF file from which this database was read.
\remarks
If the database was created not by reading the VSF file the function will return the current version which will be used for writing the VSF file.
If the rc parameter is not null and the version was successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual OdTvVSFVersion getVSFVersion(OdTvResult* rc = NULL) const = 0;
/** \details
Sets the compression options to be used when exporting the Visualize database to a VSF file or stream.
\param options [in] Structure which describes the compression options.
\returns A value of the type that contains the result of the write operation.
If the options was successfully set, the method returns the tvOk value; otherwise it throws an exception.
\remarks
The method throws an exception if the write is unsuccessful.
*/
virtual OdTvResult setVSFExportOptions(const OdTvVSFExportOptions& options) = 0;
/** \details
Returns the compression options to be used when exporting the Visualize database to a VSF file or stream.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A structure that describes the compression options.
\remarks
If the rc parameter is not null and the compression options structure was successfully returned, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual OdTvVSFExportOptions getVSFExportOptions(OdTvResult* rc = NULL) = 0;
/** \details
Writes the content of the database to a specified file.
\param filename [in] A full path to the output file.
\param pOptions [in] Pointer to a structure which describes the compression options.
\returns A value of the type that contains the result of the write operation.
If the write operation was successful, the method returns the tvOk value; otherwise it throws an exception.
\remarks
The method throws an exception if the write is unsuccessful.
This method is deprecated and will be removed soon, use writeVSFX() instead.
It is possible to use analogue from OdTvDeprecated namespace, but this analogue eventually will be removed too.
*/
virtual OdTvResult writeFile(const OdString& filename, const OdTvVSFExportOptions* pOptions = NULL) = 0;
/** \details
Writes the content of the database to a specified .VSFX file.
\param filename [in] A full path to the output .VSFX file.
\param pOptions [in] Pointer to a structure which describes the compression options.
\returns A value of the type that contains the result of the write operation.
If the write operation was successful, the method returns the tvOk value; otherwise it throws an exception.
\remarks
The method throws an exception if the write is unsuccessful.
*/
virtual OdTvResult writeVSFX( const OdString& filename, const OdTvVSFExportOptions* pOptions = NULL ) = 0;
/** \details
This method is deprecated and will be removed soon, use writeVSFX() instead.
\param buff [in] Pointer to a stream buffer.
\param pOptions [in] Pointer to a structure which describes the compression options.
\returns A value of the type that contains the result of the write operation.
If the write operation was successful, the method returns the tvOk value; otherwise it throws an exception.
\remarks
The method throws an exception if the write is unsuccessful.
It is possible to use analogue from OdTvDeprecated namespace, but this analogue eventually will be removed too.
Writes the contents of the database object to the specified stream buffer.
*/
virtual OdTvResult write(OdStreamBuf *buff, const OdTvVSFExportOptions* pOptions = NULL) = 0;
/** \details
Writes the content of the database to a specified .VSFX stream.
\param pStream [in] A smart pointer to the output .VSFX stream.
\param pOptions [in] Pointer to a structure which describes the compression options.
\returns A value of the type that contains the result of the write operation.
If the write operation was successful, the method returns the tvOk value; otherwise it throws an exception.
\remarks
The method throws an exception if the write is unsuccessful.
*/
virtual OdTvResult writeVSFX( OdStreamBufPtr pStream, const OdTvVSFExportOptions* pOptions = NULL ) = 0;
/** \details
Exports the TV database to the specified file.
\param pParams [in] A pointer to an object that contains the .
\returns The tvOk value if the export is successful; otherwise it contains an appropriate error code.
\remarks
The method throws the exception if the export operation is not successful.
*/
virtual OdTvResult exportTo(const OdTvBaseExportParams* pParams) = 0;
/** \details
Append the data from TV database to the specified file.
\param pParams [in] A pointer to an object that contains the .
\returns The tvOk value if the data is appended successfully; otherwise it contains an appropriate error code.
\remarks
The method throws the exception if the export operation is not successful.
*/
virtual OdTvResult appendTo(const OdTvBaseAppendToParams* pParams) = 0;
/** \details
Returns the name of the file associated with the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The full name of the file where the database content was previously saved
or an empty string if the database has not been saved yet.
\remarks
If the rc parameter is not null and the file name returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual OdString getFilename(OdTvResult* rc = NULL) const = 0;
/** \details
Retrieves the pointer to the internal database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A pointer to the internal database represented with a void data type pointer.
\remarks
If the rc parameter is not null and the pointer returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual void* getInternalDatabase(OdTvResult* rc = NULL) const = 0;
/** \details
Adds the Common Data Access (CDA) tree to the database and returns the appropriate ID.
\param name [in] A CDA tree storage name as a String value up to 2049 characters long.
\param pTree [in] A pointer to common data access tree object that contains the .
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created CDA tree storage object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new CDA tree storage object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the CDA tree storage object creation by calling the isNull() method of the returned identifier.
If this method returns false, the CDA tree storage object was successfully created. Otherwise the isNull() method returns true.
*/
virtual OdTvCDATreeStorageId addCDATreeStorage(const OdString& name, OdTvCDATreePtr pTree, OdTvResult* rc = NULL) = 0;
/** \details
Removes the Common Data Access (CDA) tree with the specified identifier from the database.
\param id [in] An identifier of the Common Data Access (CDA) tree that should be deleted.
\returns A value of the type that contains the result of the remove operation.
\remarks
If the specified Common Data Access (CDA) tree is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult removeCDATreeStorage(const OdTvCDATreeStorageId& id) = 0;
/** \details
Removes all Common Data Access (CDA) trees from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all Common Data Access (CDA) trees are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult clearCDATreeStorages() = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to CDA tree storages objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvCDATreeStoragesIteratorPtr getCDATreeStoragesIterator(OdTvResult* rc = NULL) = 0;
/** \details
Registers the name of an application in the database.
\param appName [in] An application name.
\param bAlreadyExist [out] A placeholder to store the flag value that indicates whether an application with specified name was already registered.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier for the registered application if the application is successfully registered;
otherwise it returns a null identifier.
\remarks
If the rc parameter is not null and the application was registered in the database, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
\sa
*/
virtual OdTvRegAppId registerAppName(const OdString& appName, bool& bAlreadyExist, OdTvResult* rc = NULL) = 0;
/** \details
Retrieves the type of an object with specified handle.
\param h [in] An object handle.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The object type represented with a enumeration value.
\remarks
If the rc parameter is not null and the type of the object was successfully retrieved, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
virtual OdTv::HandledObjectType getObjectTypeByHandle(const OdUInt64 h, OdTvResult* rc = NULL) = 0;
/** \details
Appends new data from a file to the database.
\param pParams [in] A pointer to an object that contains the .
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The model identifier if the model is successfully created and the content of the file is imported to the model;
otherwise it returns a null identifier.
\remarks
If the rc parameter is not null and the model is successfully created and filled with file content, the rc parameter accepts the tvOk value; otherwise it contains an
appropriate error code.
The method throws the exception if the append operation is not successful.
*/
virtual OdTvModelId append(const OdTvBaseImportParams* pParams, OdTvResult* rc = NULL) = 0;
/** \details
Appends new data from a file to the database.
\param pParams [in] A pointer to an object that contains the .
\param modelId [in] An identifier of the model for the appending insert object.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The block identifier if the block is successfully created and the content of the file is imported to the block; otherwise, the method returns a null identifier.
\remarks
If the rc parameter is not null and the block is successfully created and filled with file content, the rc parameter accepts the tvOk value; otherwise it contains an
appropriate error code.
The method throws the exception if the append operation fails.
*/
virtual OdTvBlockId append(const OdTvBaseImportParams* pParams, const OdTvModelId& modelId, OdTvResult* rc = NULL) = 0;
/** \details
Adds or updates partial view indexes for models of the database.
\param bUpdateExisting [in] A flag value that indicates whether the indexes, that exist in the database, should be updated (if equal to true).
\param bExtendedMode [in] A flag that indicates whether partial index should be in extended mode or not
\returns A value of the type that contains the result of the operation.
If the operation was successful, the method returns the tvOk value; otherwise it throws an exception.
\remarks
Extended Partial Index also indexes sub-entities (not only entities), which gives better visual result in request-based partial viewing.
\sa
*/
virtual OdTvResult addPartialViewIndexes(bool bUpdateExisting = true, bool bExtendedMode = false ) = 0;
/** \details
Checks that the database has partial indexes.
\param bCheckExtents [in] If true, method will also check that index has valid extents
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns true if and only if all writable models and blocks in this database have partial indexes.
\sa
*/
virtual bool hasPartialViewIndexes(bool bCheckExtents = false, OdTvResult* rc = NULL) = 0;
/** \details
Retrieves the statistics for the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The statistics object for the database.
\remarks
If the rc parameter is not null and the statistics object is successfully retrieved, the rc parameter accepts the tvOk value, otherwise it contains an
appropriate error code.
\sa
*/
virtual OdTvDatabaseStatistic getStatistic(OdTvResult* rc = NULL) = 0;
/** \details
Puts database into Partial Import mode.
\param filename [in] Specifies file (VSF) that will be used as dump file.
\returns A value of the type that contains the result of the operation.
\remarks
This functionality is designed for Partial Import and is primary for internal usage.
This method create (or re-write) specified file, but until endPartialImport() call this file will be not a valid VSF-file.
*/
virtual OdTvResult beginPartialImport( const OdString& filename ) = 0;
/** \details
Writes entity into dump file and replace it content by resolver (unloads entity).
\param id [in] Entity to be written
\returns A value of the type that contains the result of the operation.
\remarks
This functionality is designed for Partial Import and is primary for internal usage.
The database have to be in Partial Import mode before calling this method.
Calling openObject() for written entity will load it from dump file.
*/
virtual OdTvResult writeObjectPartial( OdTvEntityId id ) = 0;
/** \details
Ends Partial Import database mode.
\returns A value of the type that contains the result of the operation.
\remarks
This functionality is designed for Partial Import and is primary for internal usage.
This method writes in the dump file all non-dumped data. After it the dump file becomes correct VSF-file.
However, database state is not equal to Partial Loaded database state, so it is strongly recommended to remove it and re-read database from the dump file.
*/
virtual OdTvResult endPartialImport() = 0;
/** \details
Disables the internal notifications about the modifications of objects. Notifications are automatically
enabled when OdTvGsDevice::update() is called.
\returns
An value: tvOk if the internal notifications are disabled;
otherwise, the method returns an appropriate error code.
*/
virtual OdTvResult disableInternalNotifications() = 0;
/** \details
Returns the OdTvEntityId that matches the original database handle.
\param originalDatabaseHandle [in] Original database handle.
\param bNeedSearchInBlocks [in] A flag that indicates, should make search in blocks or not.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns The entity identifier if the entity is found by the original handle, otherwise it returns a null identifier.
\remarks
First call could be slow because of entities caching.
If the rc parameter is not null and the entity is successfully found, the rc parameter accepts the tvOk value; otherwise it contains an
appropriate error code.
The method throws the exception if the operation is not successful.
In some cases, like after 'append' operation, one original handle can correspond to several entities in the Visualize database.
In this case this method will return first matched entity and 'tvWarning' return code.
In this situation it is need to use 'findEntities' methos to receive all matched entities.
\sa
*/
virtual OdTvEntityId findEntity(OdUInt64 originalDatabaseHandle, bool bNeedSearchInBlocks = true, OdTvResult* rc = NULL) = 0;
/** \details
Returns the array of OdTvEntityIds that matches the original database handle.
\param originalDatabaseHandle [in] Original database handle.
\param bNeedSearchInBlocks [in] A flag that indicates, should make search in blocks or not.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An array of entity identifiers if the entities are found by the original handle, otherwise it returns an empty array.
\remarks
First call could be slow because of entities caching.
If the rc parameter is not null and the entities are successfully found, the rc parameter accepts the tvOk value; otherwise it contains an
appropriate error code.
The method throws the exception if the operation is not successful.
This method is need when the original handle can correspond to several entities in the Visualize database.
Such situation is possible after 'append' operation. In other cases it is simpler to use 'findEntity' method.
\sa
*/
virtual OdTvEntityIdsArray findEntities(OdUInt64 originalDatabaseHandle, bool bNeedSearchInBlocks = true, OdTvResult* rc = NULL) = 0;
/** \details
Sets a host app progress meter which will be used for direction the info about import process to the host app
\param pProgressMeter [in] A pointer to an OdDbHostAppProgressMeter object
\returns
The of setting the host app progress meter.
If the progress meter is successfully set, the method returns the tvOk value;
otherwise, the method returns an appropriate error code.
\remarks
Currently, progress metering is supported for vectorization.
*/
virtual OdTvResult setProgressMeter(OdTvHostAppProgressMeter* pProgressMeter) = 0;
/** \details
Sets the given code page to database.
\param cp [in] Value for the code page.
\returns A value of the type that contains the result of the operation.
*/
virtual OdTvResult setCodePage(OdCodePageId cp) = 0;
/** \details
Creates a new animation action object.
\param name [in] An animation action name represented with a string value up to 2049 characters long.
\param bNeedSaveInFile [in] Flag that specifies whether the animation action should be saved in a file.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created animation action object if the creation is successful, or returns a null identifier.
*/
virtual OdTvAnimationActionId createAnimationAction( const OdString& name, bool bNeedSaveInFile = true, OdTvResult* rc = NULL ) = 0;
/** \details
Removes an animation action object with the given ID.
\param id [in] ID of an animation action object.
\returns A value of the type that contains the result of the operation.
*/
virtual OdTvResult removeAnimationAction( const OdTvAnimationActionId& id ) = 0;
/** \details
Removes all animation actions.
\returns A value of the type that contains the result of the operation.
*/
virtual OdTvResult clearAnimationActions() = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to animation action objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvAnimationActionsIteratorPtr getAnimationActionsIterator( OdTvResult* rc = NULL ) = 0;
/** \details
Creates a new animation container object.
\param name [in] An animation container name represented with a string value up to 2049 characters long.
\param bNeedSaveInFile [in] Flag that specifies whether the animation container should be saved in a file.
\param rc [out] A pointer to a value of the type that contains the result of the creation.
\returns An identifier of the created animation container object if the creation is successful, or returns a null identifier.
*/
virtual OdTvAnimationContainerId createAnimationContainer( const OdString& name, bool bNeedSaveInFile = true, OdTvResult* rc = NULL ) = 0;
/** \details
Removes an animation container object with the given ID.
\param id [in] ID of an animation container object.
\returns A value of the type that contains the result of the operation.
*/
virtual OdTvResult removeAnimationContainer( const OdTvAnimationContainerId& id ) = 0;
/** \details
Removes all animation containers.
\returns A value of the type that contains the result of the operation.
*/
virtual OdTvResult clearAnimationContainers() = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to animation container objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvAnimationContainersIteratorPtr getAnimationContainersIterator( OdTvResult* rc = NULL ) = 0;
/** \details
Sets a new path to a custom folder that contains image files used as textures, backgrounds or as separate objects.
\param strFolderPath [in] A string that contains the new folder path.
\returns A value of the type that contains the result of the operation.
\remarks
If the new path to the custom image folder was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setCustomImageFolder(const OdString& strFolderPath) = 0;
/** \details
Retrieves the current path to the custom folder that contains image files used as textures, backgrounds or as separate objects.
\param rc [out] A pointer to a value of the type that contains the result of the retrieve operation.
\returns A string that contains the path to the current custom image folder.
\remarks
If the rc parameter is not null and the current path to the custom image folder was successfully returned, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdString getCustomImageFolder(OdTvResult* rc = NULL) const = 0;
/** \details
Returns the units used for drawing the contents of this database.
\param userDefCoefToMeters[out] User defined coefficient to meters transform. Actual only for 'kUserDefined' units.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns Measuring units set for the first model of the database.
\remarks
If the 'rc' parameter is not null and the units was successfully returned, the 'rc' parameter accepts the tvOk value,
otherwise it contains an appropriate error code. The method returns a value that corresponds to the measuring units set for one of
models in the database. This value is for reference only and cannot be used as measuring units. For this purpose use the model's units.
*/
virtual OdTv::Units getUnits(double* userDefCoefToMeters = NULL, OdTvResult* rc = NULL) const = 0;
/** \details
Sets a visual style object as a preferable for appropriate type.
\param type [in] A type of preferable visual style.
\param visStyleId [in] A visual style object for preferable visual style type.
\returns A value of the type that contains the result of the operation.
\remarks
If the visual style object was successfully set, the method returns the tvOk value; otherwise it returns an appropriate error code.
*/
virtual OdTvResult setPreferableVisualStyle(PreferableVisualStylesType type, const OdTvVisualStyleId& visStyleId) = 0;
/** \details
Retrieves the visual style object for appropriate preferable visual style type.
\param type [in] A type of preferable visual style.
\param rc [out] A pointer to a value of the type that contains the result of the retrieve operation.
\returns A visual style object for appropriate preferable visual style type.
\remarks
If the rc parameter is not null and the preferable visual style was successfully applied, the rc parameter accepts the tvOk value; otherwise it contains an appropriate error code.
*/
virtual OdTvVisualStyleId getPreferableVisualStyle(PreferableVisualStylesType type, OdTvResult* rc = NULL) const = 0;
/** \details
Checks that the visual style is preferable.
\param visStyleId [in] A visual style object.
\param type [out] A type of preferable visual style.
\param rc [out] A pointer to a value of the type that contains the result of the retrieve operation.
\returns A value of the type that contains the result of the operation.
*/
virtual bool isPreferableVisualStyle(const OdTvVisualStyleId& visStyleId, PreferableVisualStylesType& type, OdTvResult* rc = NULL) const = 0;
/** \details
Defines findEntityByHandle result type.
*/
enum FindEntityResult
{
/** No object found. */
kResultNotFound = 0,
/** Object found, result presented as OdTvEntityId. */
kResultEntityId = 1,
/** Object found, result presented as OdTvGeometryDataId. */
kResultGeomertyId = 2
};
/** \details
Searches for an entity or subentity using an entity handle.
\param handle [in] An entity handle.
\param entityId [out] Found OdTvEntityId.
\param geometryId [out] Found OdTvGeometryDataId.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns Type of found result.
\remarks
If the rc parameter is not null and the entity is found, the rc parameter accepts the tvOk value, otherwise it contains an
appropriate error code.
If the entity is not found, the method returns a null identifier (i.e. the isNull() method of the identifier returns true).
This method can found Entity, Insert, Camera and Light as OdTvEntityId and SubEntity as OdTvGeometryDataId.
*/
virtual FindEntityResult findEntityByHandle( OdUInt64 handle, OdTvEntityId& entityId, OdTvGeometryDataId& geometryId, OdTvResult* rc = NULL ) const = 0;
/** \details
Searches for an entity using an entity handle.
\param h [in] An entity handle.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the found entity.
\remarks
If the rc parameter is not null and the entity is found, the rc parameter accepts the tvOk value, otherwise it contains an
appropriate error code.
If the entity is not found, the method returns a null identifier (i.e. the isNull() method of the identifier returns true).
*/
virtual OdTvEntityId findEntityByHandle( OdUInt64 handle, OdTvResult* rc = NULL ) const = 0;
/**
Checks that database contains stored Gs Cache.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns true if and only if database contains stored Gs Cache.
*/
virtual bool hasStoredGsCache( OdTvResult* rc = NULL ) const = 0;
/** \details
Defines the stored Gs Cache status.
*/
enum class DeviceGsCacheInfo
{
/** Gs Cache for the specified device is founded. */
kGsCacheFounded = 0,
/** Database does not store Gs Cache at all. */
kDatabaseHasNoGsCache = 1,
/** Database does not store Gs Cache for the specified device. */
kNoAppropriateGsCache = 2,
/** Database does store Gs Cache for the specified device, but it Block Cache option differ. */
kBlockCacheOptionMismatch = 3
};
/**
Checks that database contains stored Gs Cache for the specified device.
\param deviceId [in] OdTvGsDevice identifier whose cache should be looked for.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns Gs Cache status for specified device.
*/
virtual DeviceGsCacheInfo hasStoredGsCache( OdTvGsDeviceId deviceId, OdTvResult* rc = NULL ) const = 0;
/** \details
Creates a ray trace render settings object as a copy of the given render settings object and returns the appropriate ID.
\param name [in] A render settings name as a String value up to 2049 characters long.
\param vsId [in] A render settings object to copy from, represented with its identifier.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created render settings object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new render settings object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the render settings object creation by calling the isNull() method of the returned identifier.
If this method returns false, the render settings object was successfully created. Otherwise the isNull() method returns true.
*/
virtual OdTvRtRenderSettingsId createRayTraceRenderSettings(const OdString& name, const OdTvRtRenderSettingsId& rsId, OdTvResult* rc = nullptr) = 0;
/** \details
Creates a ray trace render settings object as a default render settings object and returns the appropriate ID.
\param name [in] A render settings name as a String value up to 2049 characters long.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns An identifier of the created render settings object if the creation is successful, or returns a null identifier.
If the rc parameter is not NULL and a new render settings object is successfully created, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is NULL, you can check the result of the render settings object creation by calling the isNull() method of the returned identifier.
If this method returns false, the render settings object was successfully created. Otherwise the isNull() method returns true.
*/
virtual OdTvRtRenderSettingsId createRayTraceRenderSettings(const OdString& name, OdTvResult* rc = nullptr) = 0;
/** \details
Removes a ray trace render settings object with the specified identifier from the database.
\param id [in] An identifier of the render settings object that should be deleted.
\returns A value of the type that contains the result of the remove operation.
If the specified render settings object is successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult removeRayTraceRenderSettings(const OdTvRtRenderSettingsId& id) = 0;
/** \details
Removes all ray trace render settings objects from the database.
\returns A value of the type that contains the result of the remove operation.
\remarks
If all render settings objects are successfully removed, the method returns tvOk; otherwise it returns an appropriate error code.
*/
virtual OdTvResult clearRayTraceRenderSettingss() = 0;
/** \details
Searches for a ray trace render settings object with a specified name in the database.
\param name [in] A name of the ray trace render settings object to be found.
\param rc [out] A pointer to a value of the type that contains the result of the search.
\returns An identifier of the found render settings object if it is found; otherwise it returns a null identifier.
\remarks
To check whether the returned identifier is null, call the isNull() method.
In addition, if the rc parameter is not null, it accepts the tvOk value if the render settings object was found; otherwise it contains an
appropriate error code.
*/
virtual OdTvRtRenderSettingsId findRayTraceRenderSettings(const OdString& name, OdTvResult* rc = nullptr) const = 0;
/** \details
Returns a smart pointer to an iterator object to get sequential access to ray trace render settings objects in the database.
\param rc [out] A pointer to a value of the type that contains the result of the operation.
\returns A smart pointer to the iterator.
\remarks
If the rc parameter is not null and the iterator returned by the method is correct, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
If the rc parameter is null (or not passed in a calling subroutine),
you can check whether the correct iterator was returned by the method
by checking whether the returned smart pointer is not NULL.
*/
virtual OdTvRtRenderSettingsIteratorPtr getRayTraceRenderSettingsIterator(OdTvResult* rc = nullptr) const = 0;
};
/** \details
A data type that represents a smart pointer to an object.
*/
typedef OdTvSmartPtr OdTvDatabasePtr;
/** \details
The interface class for a database object identifier that allows access to the object.
*/
class ODTV_EXPORT OdTvDatabaseId : public OdTvLinkId
{
public:
/** \details
Opens the database determined with its identifier for a read or write operation.
\param mode [in] An open mode value.
\param rc [out] A pointer to a value of the type that contains the result of the open operation.
\returns A smart pointer to the database object.
\remarks
If the rc parameter is not null and the database is successfully opened, the rc parameter accepts the tvOk value;
otherwise it contains an appropriate error code.
*/
OdTvDatabasePtr openObject(OdTv::OpenMode mode = OdTv::kForRead, OdTvResult* rc = NULL) const;
};
#endif //_ODTV_DATABASE_H_INCLUDED_