SCENE C++ API  2.0.27
Public Member Functions | Static Public Member Functions | List of all members
LSGenericBinaryObject Class Reference

Interface to create and read generic binary objects. More...

#include <lsgenericbinaryobject.h>

+ Inheritance diagram for LSGenericBinaryObject:

Public Member Functions

ref_ptr< LSBinaryReadergetData ()
 Returns an binary data iterator that can be used to read the binary data. More...
 
size_t getSize () const
 Returns the exact overall size of the data. More...
 
LSString getMimeType () const
 Returns the MIME type string of the Generic Binary Object. More...
 
LSString getContext () const
 Returns the context string of the Generic Binary Object. More...
 
LSString getId () const
 Returns the ID string of the Generic Binary Object. More...
 
- Public Member Functions inherited from LSObject
Eigen::Matrix4d getTransformationToGlobal () const
 Calculates the transformation matrix which transforms local object coordinates to global coordinates. More...
 
void select ()
 Selects this object. More...
 
LSIterator< ref_ptr< LSObject > > getChildIterator () const
 Gets an iterator which can be used for a breadth-first iteration over all objects below the object in the object hierarchy. More...
 
ref_ptr< LSObjectgetParent () const
 Returns the parent of this object. More...
 
unsigned int getNumChildren () const
 Returns the number of children of this object. More...
 
ref_ptr< LSObjectgetChild (unsigned int n) const
 Returns the n-th child of this object. More...
 
ref_ptr< LSObjectgetChild (LSString name) const
 Returns the child of this object with a given name. More...
 
bool rmChild (unsigned int n)
 Removes a child from this object. More...
 
bool rmChild (LSString name)
 Removes a child from this object. More...
 
LSResult::Result addChild (LSString name, LSString typeName, ref_ptr< LSObject > &childOut)
 Creates a new child of the given type. More...
 
LSResult::Result generateUniqueChildName (const LSString &baseName, LSString &nameOut) const
 Generates a valid and unique name for a new child of this object based on the provided base name. More...
 
LSResult::Result setParent (ref_ptr< LSObject > newParent)
 Changes the parent of this object. More...
 
- Public Member Functions inherited from LSAttributeContainer
LSString getTypeName () const
 Gets the type name of this instance. More...
 
LSString getName () const
 Gets the name of the container. More...
 
LSResult::Result setName (LSString name)
 Sets the name of the container. More...
 
LSString getUuid () const
 Returns the unique id of the container. More...
 
LSString assignUuid ()
 Assigns a unique id to the container if the container does not not yet have a unique id. More...
 
unsigned int getNumAttributes () const
 Get the number of attributes in the container. More...
 
LSString getAttributeName (unsigned int index) const
 Get the name of an attribute in the container. More...
 
unsigned int getAttributeIndex (LSString name) const
 Get the index of an attribute in the container. More...
 
LSAttribute getAttribute (unsigned int index) const
 Get an attribute based on its index. More...
 
LSAttribute getAttribute (LSString name) const
 Get an attribute based on its name. More...
 
LSResult::Result setAttribute (unsigned int index, const LSAttribute &attribute)
 Set an attribute based on its index. More...
 
LSResult::Result setAttribute (LSString name, const LSAttribute &attribute)
 Set an attribute based on its name. More...
 
LSResult::Result addCustomAttribute (LSString name, const LSAttribute &attribute)
 Add a new custom attribute to the container. More...
 
bool removeCustomAttribute (LSString name)
 Remove a custom attribute from the container. More...
 
unsigned int getNumFields () const
 Returns the number of fields in the container. More...
 
ref_ptr< LSAttributeContainergetField (unsigned int index) const
 Returns the field at position n in the container. More...
 
ref_ptr< LSAttributeContainergetField (const LSString &name) const
 Returns the field with the given name. More...
 
LSResult::Result addField (const LSString &name, const LSString &typeName, ref_ptr< LSAttributeContainer > &fieldOut)
 Add a field to the container. More...
 
bool rmField (const LSString &name)
 Removes the field with a given name from the container. More...
 

Static Public Member Functions

static LSResult::Result createGenericBinaryObject (const ref_ptr< LSObject > &parent, const LSString &name, const LSString &context, const LSString &id, const LSString &filePath, ref_ptr< LSGenericBinaryObject > &gbo, const LSString &mimetype=LSString())
 Create a Generic Binary Object from a given file. More...
 
static LSResult::Result createGenericBinaryObject (const ref_ptr< LSObject > &parent, const LSString &name, const LSString &context, const LSString &id, const LSString &mimeType, const ref_ptr< LSBinaryReader > &source, ref_ptr< LSGenericBinaryObject > &gbo)
 Create a GenericBinaryObject from a custom data source. More...
 

Additional Inherited Members

- Protected Member Functions inherited from LSRefType
void ref () const
 Increments the internal reference counter. More...
 
void unref () const
 Decrements the internal reference counter. More...
 

Detailed Description

Interface to create and read generic binary objects.

Generic binary objects (GBOs) can store user-defined data inside a SCENE project. GBOs are not visible in the SCENE structure tree, but behave otherwise like other SCENE objects. An good example use case would be to store additional binary data that can be only understood by your plugin app or standalone app inside a SCENE project to make it self-contained. Please remember that older API versions might not fully support SCENE projects with GBOs. GBOs can be created below many different parent objects. Useful examples are the root object, clusters or scans.

Version
SCENE API version 2.0.26.

Member Function Documentation

◆ getData()

ref_ptr<LSBinaryReader> getData ( )

Returns an binary data iterator that can be used to read the binary data.

The returned iterator object will have an exclusive read lock on the GBO while its alive! Make sure to free the binary data iterator as soon as possible.

See also
LSBinaryReader
Returns
A nullptr in case of any unexpected errors.
Version
SCENE API Version 2.0.26

◆ getSize()

size_t getSize ( ) const

Returns the exact overall size of the data.

May be slow for large objects since it requires to stream through the data once.

Version
SCENE API Version 2.0.26

◆ getMimeType()

LSString getMimeType ( ) const

Returns the MIME type string of the Generic Binary Object.

See also: https://www.iana.org/assignments/media-types/media-types.xhtml

Version
SCENE API Version 2.0.26

◆ getContext()

LSString getContext ( ) const

Returns the context string of the Generic Binary Object.

The context string is user-defined and used to group the same type of objects.

Version
SCENE API Version 2.0.26

◆ getId()

LSString getId ( ) const

Returns the ID string of the Generic Binary Object.

The ID string is user-defined and used to identify objects inside the same context.

Version
SCENE API Version 2.0.26

◆ createGenericBinaryObject() [1/2]

static LSResult::Result createGenericBinaryObject ( const ref_ptr< LSObject > &  parent,
const LSString name,
const LSString context,
const LSString id,
const LSString filePath,
ref_ptr< LSGenericBinaryObject > &  gbo,
const LSString mimetype = LSString() 
)
static

Create a Generic Binary Object from a given file.

The MIME type can be set automatically based on file extension.

Parameters
parentParent object reference.
nameThe tree object name to be set for the object.
contextUser-defined context string. Should be used to group the same type of GBOs.
idUser-defined ID string. Should be used to identify GBOs inside the same context.
filePathPath to the file from which to read the data.
gboReturns the new Generic Binary Object.
mimeTypeOptional MIME type. If left empty, it will be derived from the file extension.
Returns
LSResult::Ok The GenericBinaryObject was created successfully. LSResult::InvalidRequest Supplied an invalid or unsupported parent object. LSResult::ReadWrite Unable to read file. LSResult::Unauthorized You do not have the API key required to create Generic Binary Objects.
Version
SCENE API Version 2.0.26.

◆ createGenericBinaryObject() [2/2]

static LSResult::Result createGenericBinaryObject ( const ref_ptr< LSObject > &  parent,
const LSString name,
const LSString context,
const LSString id,
const LSString mimeType,
const ref_ptr< LSBinaryReader > &  source,
ref_ptr< LSGenericBinaryObject > &  gbo 
)
static

Create a GenericBinaryObject from a custom data source.

You need to provide a custom implementation of the LSBinaryReader interface. Please keep in mind that this implementation is not suited for very large data that does not easily fit into the computers main memory. For very big objects, we recommend to use the file based interface for creation.

Parameters
parentThe parent object reference.
nameThe name to be set for the GenericBinaryObject.
contextUser-defined context string. Should be used to group the same type of GBOs.
idUser-defined ID string. Should be used to identify GBOs inside the same context.
mimeTypeMIME type string for the data. Example: "image/jpeg"
sourceAn LSBinaryReader instance you need to implement for providing the binary data.
gboReturns the new created GenericBinaryObject.
Returns
LSResult::Ok The GenericBinaryObject was created successfully. LSResult::InvalidRequest Supplied an invalid or unsupported parent object. LSResult::ReadWrite Unable to read the data source to the end. LSResult::Unauthorized You do not have the API key required to create Generic Binary Objects.
See also
LSBinaryReader
Version
SCENE API Version 2.0.26.