3ds Max Plugins

DataBlock class for reading and writing hierarchically structured data.

Defines

INLINE

real

class DataBlock

#include <datablk.h>

Class for reading and writing hierarchically structured data.

DataBlock itself is a node of the tree that has a name and hosts typified named parameters and named sub-nodes.

Parameter or sub-block name can be non-unique for a given DataBlock object. This is useful for enumerating data that can be repeated arbitrary number of times.

For clarity, names are restricted to C indentifier rules.

Actual names are stored in NameMap that is shared by all DataBlocks in the tree. Blocks and parameters use integer ids to address names in the NameMap, so there are methods that take name ids and those that take character strings. You can use name ids when you look for multiple blocks or parameters with the same name for performance gain.

DataBlock tree contents can be serialized in binary or text form.

Text files of this format usually have extension “.blk”.

Loading

bool loadText(char *text, int text_length, const char *filename = NULL): Load DataBlock tree from specified text. Filename is for error output only.

bool loadText(Tab<char> &text, const char *filename = NULL): Load DataBlock tree from specified text. Filename is for error output only.

Note

This method will modify text when including files.

bool loadFromStream(FILE *crd, const char *fname = NULL): Load DataBlock tree from arbitrary stream Data may be presented like text, binary or stream data created by function beginTaggedBlock(_MAKE4C(‘blk’)) fname uses if loading from text file to right parse include directives

bool load(const char *fname): Load DataBlock tree from any type of file, binary or text First function try to load file as binary, in fail case it try to load file as text

Saving

bool saveToTextFile(const char *filename) const: Save this DataBlock (and its sub-tree) to the specified file (text form)

void saveToStream(GeneralSaveCB &cwr) const: Save this DataBlock (and its sub-tree) to arbitrary stream (binary form)

bool saveToBinaryFile(const char *filename) const: Save this DataBlock (and its sub-tree) to the specified file (binary form)

Names

int getNameId(const char *name) const: Returns name id from NameMap, or -1 if there’s no such name in the NameMap.

const char *getName(int name_id) const: Returns name by name id, uses NameMap. Returns NULL if name id is not valid.

void fillNameMap(NameMap *stringMap) const

Block Name

inline int getBlockNameId() const: Returns name id of this DataBlock.

inline const char *getBlockName() const: Returns name of this DataBlock.

Sub-blocks

inline int blockCount() const: Returns number of sub-blocks in this DataBlock. Use for enumeration.

DataBlock *getBlock(int block_number) const: Returns pointer to i-th sub-block.

DataBlock *getBlockByName(int name_id, int start_after = -1) const: Returns pointer to sub-block with specified name id, or NULL if not found.

inline DataBlock *getBlockByName(const char *name, int start_after = -1) const: Returns pointer to sub-block with specified name, or NULL if not found.

inline DataBlock *getBlockByNameEx(const char *name, DataBlock *def_blk) const: Get sub-block by name, returns def_blk, if not found.

inline DataBlock *getBlockByNameEx(const char *name) const: Get block by name, returns (always valid) emptyBlock, if not found.

DataBlock *addBlock(const char *name): Add block or get existing one. See also addNewBlock() and getBlockByNameEx(const char *name) const.

DataBlock *addNewBlock(const char *name): Add new block. See also addBlock().

void setParamsFrom(const DataBlock *copy_from): Copies all parameters (not sub-blocks!) from specified DataBlock.

DataBlock *addNewBlock(const DataBlock *copy_from, const char *as_name = NULL): Create new block as a copy of specified DataBlock, with copy of all its sub-tree.

Note

Specified DataBlock can be from different DataBlock tree.

bool removeBlock(const char *name): Remove all sub-blocks with specified name. Returns false if no sub-blocks were removed.

inline DataBlock *setBlock(const DataBlock *blk, const char *as_name = NULL): Similar to addNewBlock(const DataBlock *copy_from, const char *as_name), but removes existing sub-blocks with the same name first.

void setFrom(const DataBlock *from): Clears data, then copies all parameters and sub-blocks from specified DataBlock.

Parameters - Getting and Enumeration

inline int paramCount() const: Returns number of parameters in this DataBlock. Use for enumeration.

int getParamType(int param_number) const: Returns type of i-th parameter. See ParamType enum.

int getParamNameId(int param_number) const: Returns i-th parameter name id. See getNameId().

inline const char *getParamName(int param_number) const: Returns i-th parameter name. Uses getName().

int findParam(int name_id, int start_after = -1) const: Find parameter by name id. Returns parameter index or -1 if not found.

inline int findParam(const char *name, int start_after = -1) const: Find parameter by name. Uses getNameId(). Returns parameter index or -1 if not found.

inline bool paramExists(int name_id, int start_after = -1) const: Returns true if there is parameter with specified name id in this DataBlock.

inline bool paramExists(const char *name, int start_after = -1) const: Returns true if there is parameter with specified name in this DataBlock.

Parameters - Getting by Index

These methods get parameter value by parameter index in the block, the index number is from 0 to paramCount() -1.

On parameter type mismatch, zero-like value is returned.

Use them for enumerating parameters together with DataBlock::getParamNameId() / DataBlock::getParamName() and DataBlock::getParamType().

const char *getStr(int param_number) const

bool getBool(int param_number) const

int getInt(int param_number) const

real getReal(int param_number) const

Point2 getPoint2(int param_number) const

Point3 getPoint3(int param_number) const

Point4 getPoint4(int param_number) const

IPoint2 getIPoint2(int param_number) const

IPoint3 getIPoint3(int param_number) const

E3DCOLOR getE3dcolor(int param_number) const

TMatrix getTm(int param_number) const

Parameters - Getting by Name

These methods get parameter value by parameter name.

If there is no parameter with specified name in this DataBlock, or it has different type, default value is returned.

If there is more than one matching parameter, value of the first one is returned.

const char *getStr(const char *name, const char *def) const

bool getBool(const char *name, bool def) const

int getInt(const char *name, int def) const

real getReal(const char *name, real def) const

Point2 getPoint2(const char *name, const Point2 &def) const

Point3 getPoint3(const char *name, const Point3 &def) const

Point4 getPoint4(const char *name, const Point4 &def) const

IPoint2 getIPoint2(const char *name, const IPoint2 &def) const

IPoint3 getIPoint3(const char *name, const IPoint3 &def) const

E3DCOLOR getE3dcolor(const char *name, E3DCOLOR def) const

TMatrix getTm(const char *name, TMatrix &def) const

Parameters - Setting

These methods set value of the parameter with the specified name.

If parameter of requested type doesn’t exist, it’s added, otherwise its value is set to the specified one.

int setStr(const char *name, const char *value)

int setBool(const char *name, bool value)

int setInt(const char *name, int value)

int setReal(const char *name, real value)

int setPoint2(const char *name, const Point2 &value)

int setPoint3(const char *name, const Point3 &value)

int setPoint4(const char *name, const Point4 &value)

int setIPoint2(const char *name, const IPoint2 &value)

int setIPoint3(const char *name, const IPoint3 &value)

int setE3dcolor(const char *name, const E3DCOLOR value)

int setTm(const char *name, const TMatrix &value)

Parameters - Adding

These methods add new parameter with the specified name.

It’s possible to add multiple parameters with the same name and type.

If you want just to add / set single parameter value, use set* methods.

int addStr(const char *name, const char *value)

int addBool(const char *name, bool value)

int addInt(const char *name, int value)

int addReal(const char *name, real value)

int addPoint2(const char *name, const Point2 &value)

int addPoint3(const char *name, const Point3 &value)

int addPoint4(const char *name, const Point4 &value)

int addIPoint2(const char *name, const IPoint2 &value)

int addIPoint3(const char *name, const IPoint3 &value)

int addE3dcolor(const char *name, const E3DCOLOR value)

int addTm(const char *name, const TMatrix &value)

Parameters - Removing

bool removeParam(const char *name): Remove all parameters with the specified name. Returns false if no parameters were removed.

Other methods

inline bool isValid() const: Returns true if data in DataBlock are valid Data can be invalid if error occured while loading file

inline DataSrc getDataSrc() const

Public Types

enum ParamType

Parameter types enum.

Values:

enumerator TYPE_NONE

enumerator TYPE_STRING: Text string.

enumerator TYPE_INT: Integer.

enumerator TYPE_REAL: real (float).

enumerator TYPE_POINT2: Point2.

enumerator TYPE_POINT3: Point3.

enumerator TYPE_POINT4: Point4.

enumerator TYPE_IPOINT2: IPoint2.

enumerator TYPE_IPOINT3: IPoint3.

enumerator TYPE_BOOL: Boolean.

enumerator TYPE_E3DCOLOR: E3DCOLOR.

enumerator TYPE_MATRIX: TMatrix.

enum DataSrc

Values:

enumerator SRC_UNKNOWN: Unknown data source.

enumerator SRC_TEXT: Data was loaded from text file.

enumerator SRC_BINARY: Data was loaded from binary file.

Public Functions

DataBlock(): Default constructor, constructs empty block.

~DataBlock(): Destructor, destroys all sub-blocks.

DataBlock(const DataBlock&): Copy constructor.

DataBlock(const char *filename): Constructor that loads DataBlock tree from specified file. If you want error checking, use default constructor and loadFile().

void clearData(): Delete all sub-blocks.

void reset(): Reset DataBlock object (clear all data & names).

Public Static Attributes

static DataBlock *emptyBlock = NULL

Warning

doxygenfile: Cannot find file “e3DCOLOR.H

common classes and functions for 2D, 3D and 4D math

class Matrix33: #include <math3d.h>

class TMatrix

#include <math3d.h>

4x3 transformation matrix. last column (3rd, counting from zero) is translation