Generic Attributes
Attributes are general purpose data that can be associated to any entity. Using an A3DRootBase instance, you can browse all its attributes.
Reading or writing generic attributes involves good knowledge on attributes hierarchy:
An A3DMiscSingleAttributeData instance can hold any value of the following types:
32-bit integer.
32-bit floating-point (IEEE 754).
UTF-8 C-Style string.
An A3DMiscAttribute instance groups any number of A3DMiscSingleAttributeData together.
An A3DRootBase instance can hold any number of A3DMiscAttribute.
This page is a general presentation on how to read attributes from any ref A3DRootBase instance.
Reading a Single Attribute Instance
A single attribute is an instance of A3DMiscSingleAttributeData, a data-only structure which is described as:
typedef struct
{
A3DUns16 m_usStructSize;
A3DBool m_bTitleIsInt;
A3DUTF8Char* m_pcTitle;
A3DEModellerAttributeType m_eType;
A3DUTF8Char* m_pcData;
A3DUns16 m_usUnit;
} A3DMiscSingleAttributeData;
Any attribute is a Title/Value pair where:
m_pcTitle is either a C-string or a 32 bit unsigned integer.
m_pcData is of any of the above mentioned type.
32-Bit Integer Data
If m_eType == kA3DModellerAttributeTypeInt the data is stored as a 32-bit integer data (A3DUns32):
if(in_sAttr.m_eType == kA3DModellerAttributeTypeInt)
{
A3DUns32 uiData;
memcpy(&uiData, in_sAttr.m_pcData, sizeof(A3DUns32));
printf("Value: %d", uiData);
}
32-Bit Floating Point
If m_eType == kA3DModellerAttributeTypeReal the data is stored as a 32-bit floating point data (A3DFloat):
if(in_sAttr.m_eType == kA3DModellerAttributeTypeReal)
{
A3DFloat uiData;
memcpy(&uiData, in_sAttr.m_pcData, sizeof(A3DFloat));
printf("Value: %f", uiData);
}
When the value is a floating-point the field m_usUnit is used to specify a unit for this value. If no unit is provided, m_usUnit is set to A3D_DEFAULT_NO_UNIT.
For more information about generic unit specifiers, see [the unit attributes page](unit_attributes.html).
UTF-8 C-String
If m_eType == kA3DModellerAttributeTypeString the data is stored as a null-terminated UTF-8 string (A3DUTF8Char*):
if(in_sAttr.m_eType == kA3DModellerAttributeTypeString)
{
A3DUTF8Char* pcData = in_sAttr.m_pcData;
printf("Value: %s", uiData);
}
Time Specifier
If m_eType == kA3DModellerAttributeTypeTime the data is stored as a time specifier as defined by the [time_t specifications](https://en.cppreference.com/w/c/chrono/time_t):
if(in_sAttr.m_eType == kA3DModellerAttributeTypeString)
{
time_t iData;
memcpy(&iData, in_sAttr.m_pcData, sizeof(A3DInt32));
printf("Value: %s", asctime(gmtime(&iData)));
}
Reading an Attribute
An attribute is an instance of A3DMiscAttribute. Any attribute has a title and zero or more A3DMiscSingleAttributeData:
void ReadAttribute(const A3DMiscAttribute* in_pAttribute)
{
A3DMiscAttributeData sAttributeData;
A3D_INITIALIZE_DATA(A3DMiscAttributeData, sAttributeData);
A3DMiscAttributeGet(in_pAttribute, &sAttributeData);
// Iterate through the single attributes
const A3DUns32 uiNSingleAttributes = sAttributeData.m_uiSize;
fo(A3DUns32 sa = 0 ; sa < uiNSingleAttributes ; ++sa)
{
const A3DMiscSingleAttributeData* pSingleAttributeData = sAttributeData.m_asSingleAttributesData + sa;
ReadSingleAttribute(pSingleAttributeData);
}
A3DMiscAttributeGet(NULL, &sAttributeData);
}
Getting the List of Attributes
Generic attributes of an A3DRootBase()
instance are available as an array:
void ReadAttributes(const A3DRootBase* in_pBase)
{
A3DRootBaseData sRootBaseData;
A3D_INITIALIZE_DATA(A3DRootBaseData, sRootBaseData);
A3DRootBaseGet(in_pBase, &sRootBaseData);
// Iterate through the attributes
const A3DUns32 uiNAttributes = sRootBaseData.m_uiSize;
for(A3DUns32 a = 0 ; a < uiNAttributes ; ++a)
{
const A3DMiscAttribute* pAttribute = sRootBaseData.m_ppAttributes[a];
ReadAttribute(pAttribute);
}
A3DRootBaseGet(NULL, &sRootBaseData);
}
All attributes are instances of A3DMiscAttribute()
.
Attribute Titles
Within A3DMiscAttributeData
and A3DMiscSingleAttributeData
, the m_pcTitle may contain:
A 32 bits unsigned integer if m_bTitleIsInt is A3D_TRUE
A traditional null-terminated string otherwise
If m_bTitleIsInt is A3D_TRUE, the A3DUTF8Char* value may directly be casted into A3DUns32* and dereferenced.
Here’s an example of function which gets the title of an attribute given its format, and prints in into a buffer:
// Reads in_pcTitle and in_bTitleIsInt to print the title into
// The buffer must be long enough to contains the formatted title.
// Returns A3D_FALSE if in_pcTitle is NULL, A3D_TRUE otherwise.
A3DBool SPrintTitle(A3FUTF8Char* in_pcTitle, A3DBool in_bTitleIsInt, A3DUTF8Char* out_pcBuffer)
{
if(in_pcTitle == NULL) {
return A3D_FALSE;
}
if (in_bTitleIsInt == A3D_TRUE) {
sprintf(out_pcBuffer, "%d", *((A3DUns32*)in_pcTitle));
} else {
wprintf(out_pcBuffer, "%s'", in_pcTitle);
}
return A3D_TRUE;
}
The following examples use SPrintTitle() for readability.
A Complete Example
The code below is a complete example which traverses an ref A3DRootBase instance and print all its attributes in the standard output in the form:
// Displays attributes as follow:
// Attribute Title0:
// SingleAttribute Title00: Value (Type): Value00
// SingleAttribute Title01: Value (Type): Value01
// Attribute Title1:
// SingleAttribute Title10: Value (Type): Value10
// SingleAttribute Title11: Value (Type): Value11
// ...
void PrintGenericAttributes(const A3DRootBase* in_pRootBase)
{
A3DRootBaseData sRootBaseData;
A3D_INITIALIZE_DATA(A3DRootBaseData, sRootBaseData);
A3DRootBaseGet(in_pRootBase, &sRootBaseData);
A3DUTF8Char pcTitle[64];
// Iterate through the attributes
const A3DUns32 uiNAttributes = sRootBaseData.m_uiSize;
for (A3DUns32 a = 0; a < uiNAttributes; ++a)
{
const A3DMiscAttribute* pAttribute = sRootBaseData.m_ppAttributes[a];
A3DMiscAttributeData sAttributeData;
A3D_INITIALIZE_DATA(A3DMiscAttributeData, sAttributeData);
A3DMiscAttributeGet(pAttribute, &sAttributeData);
// Display the attribute title
if(SPrintTitle(sAttributeData.m_pcTitle, sAttributeData.m_bTitleIsInt, pcTitle) == A3D_TRUE) {
printf("Attribute: %s\n", pcTitle);
}
// Iterate through the single attributes
const A3DUns32 uiNSingleAttributes = sAttributeData.m_uiSize;
for (A3DUns32 sa = 0; sa < uiNSingleAttributes; ++sa)
{
A3DMiscSingleAttributeData* pSingleAttributeData = sAttributeData.m_asSingleAttributesData+sa;
// Display the single attribute title
if(SPrintTitle(pSingleAttributeData.m_pcTitle, pSingleAttributeData.m_bTitleIsInt, pcTitle) == A3D_TRUE) {
printf("Attribute: %s\n", pcTitle);
}
// Display the single attribute value on the same line
switch (pSingleAttributeData->m_eType)
{
case kA3DModellerAttributeTypeInt:
printf("Value (A3DUns32): %d\n", *(A3DUns32*)pSingleAttributeData->m_pcData);
break;
case kA3DModellerAttributeTypeReal:
printf("Value (A3DFloat): %f\n", *(A3DFloat*)pSingleAttributeData->m_pcData);
break;
case kA3DModellerAttributeTypeTime:
printf("Value (Time): %s\n", asctime(gmtime((time_t*)pSingleAttributeData->m_pcData)));
break;
case kA3DModellerAttributeTypeString:
printf("Value (String): %s\n", pSingleAttributeData->m_pcData);
break;
default:
break;
}
printf("\n");
}
A3DMiscAttributeGet(NULL, &sAttributeData);
}
A3DRootBaseGet(NULL, &sRootBaseData);
}
Attributes and Categories
Organization of A3DMiscSingleAttribute
instances within A3DMiscAttribute instances is entirely up to the implementation.
Yet, upon reading any format to PRC, HOOPS Exchange organizes attributes into categories.
Note
Within a PRC tree, a category is a named A3DMiscAttribute instance grouping named A3DSingleAttributeInstances. This applies only if both A3DMiscAttribute and A3DSingleAttributeInstances instances have a title.
To sum up for any instance of A3DMiscSingleAttribute within an #A3DMiscAttribute:
If both the A3DMiscSingleAttribute and the #A3DMiscAttribute have a title, then:
A3DMiscAttribute::m_pcTitle is the name of the category.
A3DMiscSingleAttribute::m_pcTitle is the name of the attribute.
If only one of the instances have a title, there is no category and m_pcTitle is the name of the attribute.
void ReadAttributesWithCategories(const A3DRootBase* in_pRootBase) { A3DRootBaseData sRootBaseData; A3D_INITIALIZE_DATA(A3DRootBaseData, sRootBaseData); A3DRootBaseGet(in_pRootBase, &sRootBaseData); // Iterate through the attributes const A3DUns32 uiNAttributes = sRootBaseData.m_uiSize; for (A3DUns32 a = 0; a < uiNAttributes; ++a) { const A3DMiscAttribute* pAttribute = sRootBaseData.m_ppAttributes[a]; A3DMiscAttributeData sAttributeData; A3D_INITIALIZE_DATA(A3DMiscAttributeData, sAttributeData); A3DMiscAttributeGet(pAttribute, &sAttributeData); // Iterate through the single attributes const A3DUns32 uiNSingleAttributes = sAttributeData.m_uiSize; for (A3DUns32 sa = 0; sa < uiNSingleAttributes; ++sa) { A3DMiscSingleAttributeData* pSingleAttribute = sAttributeData.m_asSingleAttributesData+sa; A3DUTF8Char pcAttributeTitle[64]; A3DBool bAttributeHasTitle = SPrintTitle( pAttribute.m_pcTitle, pAttribute.m_bTitleIsInt, pcAttributeTitle ); A3DUTF8Char pcSingleAttributeTitle[64]; A3DBool bSingleAttributeHasTitle = SPrintTitle( pSingleAttribute.m_pcTitle, pSingleAttribute.m_bTitleIsInt, pcSingleAttributeTitle ); // If both the A3DMiscSingleAttribute and the A3DMiscAttribute have a title if(bAttributeHasTitle == A3D_TRUE && bSingleAttributeHasTitle == A3D_TRUE) { printf("Category: %s, Attribute Name: %s\n", pcAttributeTitle, pcSingleAttributeTitle); } else if(bAttributeHasTitle == A3D_TRUE || bSingleAttributeHasTitle == A3D_TRUE) { printf("Attribute Name: %s\n", pcAttributeTitle | pcSingleAttributeTitle); } else { printf("No Attribute or category name\n"); } printf("\n"); } A3DMiscAttributeGet(NULL, &sAttributeData); } A3DRootBaseGet(NULL, &sRootBaseData); }
While very unlikely, it remains possible that both A3DMiscAttribute and A3DMiscSingleAttribute have a NULL title.