HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
GA_PrimitiveJSON Class Referenceabstract

Provide a JSON interface to a primitive. More...

#include <GA_PrimitiveJSON.h>

+ Inheritance diagram for GA_PrimitiveJSON:

Public Member Functions

 GA_PrimitiveJSON ()
 
virtual ~GA_PrimitiveJSON ()
 
virtual int getEntries () const =0
 Return the number of data fields in the primitive private schema. More...
 
virtual bool shouldSaveField (const GA_Primitive *prim, int i, const GA_SaveMap &save) const
 
virtual const UT_StringHoldergetKeyword (int i) const =0
 
virtual bool saveField (const GA_Primitive *prim, int i, UT_JSONWriter &w, const GA_SaveMap &save) const =0
 
virtual bool saveField (const GA_Primitive *prim, int i, UT_JSONValue &value, const GA_SaveMap &save) const
 
virtual bool loadField (GA_Primitive *prim, int i, UT_JSONParser &p, const GA_LoadMap &load) const =0
 
virtual bool loadField (GA_Primitive *prim, int i, UT_JSONParser &p, const UT_JSONValue &value, const GA_LoadMap &load) const
 
virtual bool isEqual (int i, const GA_Primitive *prim1, const GA_Primitive *prim2) const =0
 
virtual bool save (const GA_Primitive *prim, UT_JSONWriter &w, const GA_SaveMap &map) const
 
virtual bool save (const GA_Primitive *prim, UT_JSONValue &v, const GA_SaveMap &map) const
 Save a single primitive to a UT_JSONValue. More...
 
virtual bool load (GA_Primitive *prim, UT_JSONParser &p, const GA_LoadMap &map) const
 
virtual bool load (GA_Primitive *prim, UT_JSONParser &p, const UT_JSONValue &value, const GA_LoadMap &map) const
 Load a single primitive from a UT_JSONValue. More...
 

Protected Member Functions

virtual bool getRunFields (const GA_Primitive **list, int list_size, const GA_SaveMap &save, UT_StringArray &varying, UT_JSONValue &uniform, uint &user_flags) const
 
virtual bool matchRun (const GA_Primitive *prim0, const GA_Primitive *prim1, const UT_StringArray &varying, const UT_JSONValue &uniform, uint user_flags) const
 
virtual bool saveRunFields (const GA_Primitive *prim, const GA_SaveMap &save, const UT_StringArray &varying, UT_JSONWriter &w, uint user_flags) const
 
virtual bool load (GA_Primitive *prim, UT_JSONParser &p, const GA_LoadMap &load, const UT_StringArray &varying, const GA_JSONUniformBlock &uniform) const
 
virtual bool loadUniform (GA_Primitive *prim, UT_JSONParser &p, const GA_LoadMap &map, const GA_JSONUniformBlock &uniform) const
 
virtual bool loadUnknownToken (GA_Primitive *prim, const char *token, UT_JSONParser &p, const GA_LoadMap &load) const
 
void init ()
 

Protected Attributes

UT_FSAmyTokens
 
int myEntries
 

Friends

class GA_PrimitiveList
 
class GA_PrimitiveRun
 

Detailed Description

Provide a JSON interface to a primitive.

This class is used in saving and loading of geometry.

See Also
GA_PrimitiveDefinition, UT_JSONWriter, UT_JSONParser

When sequences of primitives appear in order in the geometry, it's possible to compact the storage by saving the primitive instance data in a "run". This is done by storing the "fields" which appear for each primitive. The run data is an array with each item in the array representing the data fields for the individual primitive.

This eliminates the repetition of the JSON keys for each primitive. For example, the following two objects represent the same data:

"primitives" : [
[ ["type":"polygon"], ["vertices":[0,1,2], "closed":true ] ],
[ ["type":"polygon"], ["vertices":[3,4,5], "closed":true ] ],
[ ["type":"polygon"], ["vertices":[6,7,8], "closed":true ] ],
[ ["type":"polygon"], ["vertices":[9,0,1], "closed":true ] ]
]
"primitives" : [
[ "type" :"run",
"runtype" :"polygon",
"varyingfields":["vertices"],
"uniformfields":{"closed":true},
],
[
[ [0,1,2] ],
[ [3,4,5] ],
[ [6,7,8] ],
[ [9,0,1] ]
]
]

JSON Schema: GA_Primitive

A primitive is stored as an array with two entries. The first entry stores the definition of the primitive. The second entry stores the private data for the primitive.

The private data is handled by the GA_PrimitiveJSON associated with the primitive type.

{
"name" : "GA_Primitive",
"description" :
"A primitive is stored in an array of two items. The first
item stores the definition (or run information). The second
entry stores the private information for the primitive (or run
of primitives).",
"type" : "array",
"items" : [
{ "$ref" : "GA_Primitive-Definition" }, // Definition of primitive
{
"$ref" : "GA_Primitive-Data", // Single primitive data
"$ref" : "GA_Primitive-RunData", // Data for run of primitives
},
],
}

JSON Schema: GA_Primitive-Definition

The primitive definition may be the definition for a single primitive, or it may store run data. The run fields are optional, but if one is defined, all should be defined. See also: JSON Schema: GA_Primitive

{
"name" : "GA_Primitive-Definition",
"description" : "Definition of a primitive (or run of primitives)",
"type" : "orderedmap",
"properties":
{
"type":
{
"type" : "string"
"description" :
"Type of primitive. 'run' indicates a run of
primitives (see runtype, uniformfields and
varyingfields)",
}
"runtype" :
{
"type" :"string",
"description" :"Type of primitive in run",
"optional" :true,
},
"uniformfields" :
{
"type" : "object",
"description" :
"A map of the fields. The value specified is the same
for all primitives in a run",
"optional" :true,
},
"varyingfields" :
{
"type" : "array",
"items" : "string",
"description" :
"A list of strings which are varying for over the run
of primitives. The run data will be stored in the
order of the strings in this list."
"optional" :true,
},
},
}

JSON Schema: GA_Primitive-RunData

This section stores the private data for a run of primitives. The data is processed by the GA_PrimitiveJSON class associated with the primitive. The data is stored in an

{
"name" : "GA_Primitive-Data",
"description" :
"Private data for a run of primitives. Each entry represents
a distinct primitive.",
"type": "array",
"items": "any",
}

JSON-GA_Primitive-HowTo

This section describes how to write load/save methods for a primitive.

The high-level interface to primitive save/load is provided by the methods

  • getEntries()
  • getKeyword(int i)
  • saveField(const GA_Primitive*, int, UT_JSONWriter&, const GA_SaveMap&)
  • saveField(const GA_Primitive*, int, UT_JSONValue&, const GA_SaveMap&)
  • load(const GA_Primitive*, int, UT_JSONParser&, const GA_LoadMap&)
  • load(const GA_Primitive*, int, UT_JSONParser&, UT_JSONValue&, const GA_LoadMap&)
  • isEqual(int i, const GA_Primitive*, const GA_Primitive *)

The private schema is defined by a number of fields in a dictionary/map. For example, a polygon might have two fields in its private schema:

Vertex List

Open/Closed Flag

which would have an interface which looked like:

int getEntries() const { return 2; }
const UT_StringHolder &getKeyword(int i) { return i == 0 ? "vertex"_sh : "closed"_sh; }
bool saveField(const GA_Primitive *prim, int i, UT_JSONWriter &w,
const GA_SaveMap &map) const {
if (i == 0) return myVertexList->save(w, map);
return w.jsonBool(myClosedFlag);
}
bool saveField(const GA_Primitive *prim, int i, UT_JSONValue &v,
const GA_SaveMap &map) const {
if (i == 0) return myVertexList->save(v, map);
v.setBool(myClosedFlag);
return true;
}
bool loadField(GA_Primitive *prim, int i, UT_JSONParser &p,
const GA_LoadMap &map) const {
if (i == 0) return myVertexList->load(p, map);
return p.parseBool(myClosed);
}
bool loadField(const GA_Primitive *prim, int i, UT_JSONParser &p,
const UT_JSONValue &v, const GA_SaveMap &map) const {
if (i == 0) return false; // Never load from a value
return v.import(myClosed);
}
bool isEqual(int i, const GA_Primitive *p0, const GA_Primitive *p1) {
if (i == 0) return false; // Never save runs of vertex lists
return p0->myClosed == p1->myClosed;
}
Examples:
tetprim/GEO_PrimTetra.C, and tetprim/GEO_PrimTetra.h.

Definition at line 225 of file GA_PrimitiveJSON.h.

Constructor & Destructor Documentation

GA_PrimitiveJSON::GA_PrimitiveJSON ( )
virtual GA_PrimitiveJSON::~GA_PrimitiveJSON ( )
virtual

Member Function Documentation

virtual int GA_PrimitiveJSON::getEntries ( ) const
pure virtual

Return the number of data fields in the primitive private schema.

Implemented in HDK_Sample::geo_PrimTetraJSON, and GA_PrimitiveJSONExtend.

virtual const UT_StringHolder& GA_PrimitiveJSON::getKeyword ( int  i) const
pure virtual

Return the keyword associated with the i'th entry of the schema. Keywords are case insensitive, but must be specified as lower case by this method.

Implemented in HDK_Sample::geo_PrimTetraJSON, and GA_PrimitiveJSONExtend.

virtual bool GA_PrimitiveJSON::getRunFields ( const GA_Primitive **  list,
int  list_size,
const GA_SaveMap save,
UT_StringArray varying,
UT_JSONValue uniform,
uint user_flags 
) const
protectedvirtual

The GA library may optimize by saving multiple primitives of the same type in a "run". This can be done if the primitive is represented by a simple map where all primitives share common fields. For example, spheres will all have:

  • center A vertex reference for the center of the sphere
  • transform The scale/rotate transform for the primitive

getRunFields() is called only if there is a run of multiple primitives. The string array returned should be the list of all fields that the primitive needs to save. For the sphere example, it would return: [ "center", "transform" ].

Parameters
list
List of primitives to check for uniform values.
list_size
Size of the list of primitives in the run (see GA_SaveMap, geo:primrunqueue).
varying
The list of fields which are different for each primitive
uniform
This will be a UT_JSONValue::JSON_MAP value. Values which are common to every primitive can be placed in this list (instead of the varying list. Only objects which can be easily loaded from a UT_JSONValue object should be put into the uniform list, since the uniform list is pre-loaded when loading runs of primitives.
user_flags
This is an integer which can be set to any value. It is passed verbatim to matchRun() and saveRunFields(). This can be used to pass information about the run fields.

The base class returns a NULL pointer (indicating saving runs is impossible).

The user_flags is an unsigned integer value which you can modify how you wish. It's passed to the matchRun() and saveRunFields() verbatim.

The default method returns false (no run is possible)

void GA_PrimitiveJSON::init ( )
protected
virtual bool GA_PrimitiveJSON::isEqual ( int  i,
const GA_Primitive prim1,
const GA_Primitive prim2 
) const
pure virtual

Determine if the i'th entry of a primitive's private schema is equal to the value in another primitive. This determines whether the data can be created as "uniform" data a run of sequential primitives. Note uniform data appears BEFORE varying data. So if you require a ordering on your keys, you need to make all keys that require to be loaded after another key never equal to each other.

Implemented in HDK_Sample::geo_PrimTetraJSON, and GA_PrimitiveJSONExtend.

virtual bool GA_PrimitiveJSON::load ( GA_Primitive prim,
UT_JSONParser p,
const GA_LoadMap map 
) const
virtual

Load a single primitive from the UT_JSONParser. By default, this method loads the primitive from an ordered dictionary (as output by the save method).

virtual bool GA_PrimitiveJSON::load ( GA_Primitive prim,
UT_JSONParser p,
const UT_JSONValue value,
const GA_LoadMap map 
) const
virtual

Load a single primitive from a UT_JSONValue.

virtual bool GA_PrimitiveJSON::load ( GA_Primitive prim,
UT_JSONParser p,
const GA_LoadMap load,
const UT_StringArray varying,
const GA_JSONUniformBlock uniform 
) const
protectedvirtual

Load a single primitive from a run of primitives. Returns false if an error occurred, else true.

virtual bool GA_PrimitiveJSON::loadField ( GA_Primitive prim,
int  i,
UT_JSONParser p,
const GA_LoadMap load 
) const
pure virtual

Load the i'th entry of the primitive's private schema from a JSON stream.

Implemented in HDK_Sample::geo_PrimTetraJSON, and GA_PrimitiveJSONExtend.

virtual bool GA_PrimitiveJSON::loadField ( GA_Primitive prim,
int  i,
UT_JSONParser p,
const UT_JSONValue value,
const GA_LoadMap load 
) const
virtual

Load the i'th entry of the primitive's private schema from a JSON value. The parser is passed in so that errors/warnings can be added.

The default implementation just calls:

UT_AutoJSONIStream is(p, value);
return loadField(prim, i, p, load);

Reimplemented in HDK_Sample::geo_PrimTetraJSON, and GA_PrimitiveJSONExtend.

virtual bool GA_PrimitiveJSON::loadUniform ( GA_Primitive prim,
UT_JSONParser p,
const GA_LoadMap map,
const GA_JSONUniformBlock uniform 
) const
protectedvirtual

Load, and optionally cache, the uniform data for a run of primitives. Returns false if an error occurred, else true.

virtual bool GA_PrimitiveJSON::loadUnknownToken ( GA_Primitive prim,
const char *  token,
UT_JSONParser p,
const GA_LoadMap load 
) const
protectedvirtual

When the primitive loader hits an unknown map token, it will call this method to let the primitive process it. The default behaviour is to add a warning to the parser and skip the next object.

If the method returns false, parsing will stop and the load will fail.

virtual bool GA_PrimitiveJSON::matchRun ( const GA_Primitive prim0,
const GA_Primitive prim1,
const UT_StringArray varying,
const UT_JSONValue uniform,
uint  user_flags 
) const
protectedvirtual

When saving a list of primitives, the library attempts to create "runs" of like primitives. The library will create an initial run of primitives (the length of which is determined by geo:primrununique in the GA_SaveMap). This initial list determines the data elements which are uniform and varying in the run of primitives.

After this initial run, additional primitives can be added to the run if they match. This method is called to test whether the primitive matches the current run (prim0 is the first primitive in the run, prim1 is the primitive to test).

The user_flags are the flags set in getRunFields().

virtual bool GA_PrimitiveJSON::save ( const GA_Primitive prim,
UT_JSONWriter w,
const GA_SaveMap map 
) const
virtual

Save a single primitve to the UT_JSONWriter By default, this simply saves an ordered dictionary (list) with the private schema. That is:

w.beginArray();
for (int i = 0; i < getEntries(); i++) {
saveField(prim, i, w, map);
}
return json.endArray();
virtual bool GA_PrimitiveJSON::save ( const GA_Primitive prim,
UT_JSONValue v,
const GA_SaveMap map 
) const
virtual

Save a single primitive to a UT_JSONValue.

virtual bool GA_PrimitiveJSON::saveField ( const GA_Primitive prim,
int  i,
UT_JSONWriter w,
const GA_SaveMap save 
) const
pure virtual

Save the i'th entry of the primitive's schema to the JSON stream. You can assume that the GA_Primitive is the correct type (i.e. a static cast is ok).

Implemented in HDK_Sample::geo_PrimTetraJSON, and GA_PrimitiveJSONExtend.

virtual bool GA_PrimitiveJSON::saveField ( const GA_Primitive prim,
int  i,
UT_JSONValue value,
const GA_SaveMap save 
) const
virtual

Save the i'th entry of the primitive's schema to a JSON Value. This method should only be called when saving uniform data, which only happens if the equality checking returned true for the i'th entry. If the comparison fails, then this method will never be called.

The default method just calls:

return saveField(prim, i, *w, save);

Reimplemented in HDK_Sample::geo_PrimTetraJSON, and GA_PrimitiveJSONExtend.

virtual bool GA_PrimitiveJSON::saveRunFields ( const GA_Primitive prim,
const GA_SaveMap save,
const UT_StringArray varying,
UT_JSONWriter w,
uint  user_flags 
) const
protectedvirtual

saveRunFields() should save a JSON array of values, one for each field in the varying list of fields. The default method returns false.

virtual bool GA_PrimitiveJSON::shouldSaveField ( const GA_Primitive prim,
int  i,
const GA_SaveMap save 
) const
virtual

Return whether the i'th field should be saved to the JSON stream. By default, all fields are saved. However, this allows the object to "skip" some fields which don't make sense in some circumstances.

Note
At the current time, this method is ignored when saving run data.

Friends And Related Function Documentation

friend class GA_PrimitiveList
friend

Definition at line 430 of file GA_PrimitiveJSON.h.

friend class GA_PrimitiveRun
friend

Definition at line 431 of file GA_PrimitiveJSON.h.

Member Data Documentation

int GA_PrimitiveJSON::myEntries
protected

Definition at line 428 of file GA_PrimitiveJSON.h.

UT_FSA* GA_PrimitiveJSON::myTokens
protected

Definition at line 427 of file GA_PrimitiveJSON.h.


The documentation for this class was generated from the following file: