Graphics

Detailed Description

group a3d_graphics_module

Query and manipulate scene and rendering informations.

The graphics group provides the essential set of tools for describing a rendering scene, such as texturing, lighting or view information. The following entities are presents in this modules, along with their public data and access functions:

The module also provides a set of indexed data:

Any entity of the given type can be used as an A3DRootBaseWithGraphics.

General Structure
An entity of type A3DRootBaseWithGraphics embeds an A3DGraphics entity. This structure mainly provides two informations:
  • A layer which allows grouping entities with a common identifier.
  • A style index which references an A3DGraphStyleData. A3DGraphStyleData lists all graphics properties the A3DRootBaseWithGraphics is assigned to, such as drawing patterns, materials or textures.

HOOPS Exchange provides a global container (A3DGlobalData) which references each of these data using indexed lists. Thus, structures such as A3DGraphRgbColorData are obtained using an non-typed numerical index.

Indexed data
Indexed data are plain structures which are globally shared among a potentially important amount of entities within a model file. For example, the same color description can be used for all the graphics entities of a scene.

Yet, these data act as front-end for internal entities which are still referenced to by handles. The purpose of obtaining the underlying entity of an indexed data depends on the context and is generally an uncommon operation. As an example, the full PBR (Physically-Based Rendering) features is provided as an extension of A3DGraphMaterialData throughout its underlying entity. To retrieve the underlying entity of an indexed data, see A3DMiscPointerFromIndexGet.

Function Documentation

A3DStatus A3DGraphicsGet(const A3DGraphics *pGraphics, A3DGraphicsData *pData)

Fetches data from a graphics entity, given its handle.

See also

A3DGraphicsData

See also

A3DGraphicsDelete

Version
2.0

Parameters:
  • pGraphics – [in] A handle to the graphics entity to fetch data from.
  • pData – [out] The A3DGraphicsData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphicsCreate(const A3DGraphicsData *pData, A3DGraphics **ppGraphics)

Creates a new graphics entity, returning its handle. 

A3DGraphic handle = 0;
A3DGraphicData data;
A3D_INITIALIZE_DATA(A3DGraphicData, data);
// Configure data...
A3DStatus result = A3DGraphicCreate(&data, &handle);
assert(handle != 0);
Version
2.0

See also

A3DGraphicsData

See also

A3DGraphicsGet

See also

A3DGraphDirectionalLightData

See also

A3DGraphPointLightData

See also

A3DGraphSpotLightData

See also

A3DGraphSceneDisplayParametersData

Memory management
Once created, entities must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DGraphicsDelete on it.

Parameters:
  • pData – [out] The data used for graphics creation.
  • ppGraphics – [in] An address to the new handle after creation.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphicsDelete(A3DGraphics *pGraphics)

Deletes an A3DGraphics entity.

Once created with A3DGraphicsCreate, a graphics entity must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DGraphicsDelete on it.

Version
2.0

See also

A3DGraphicsData

See also

A3DGraphicsCreate

See also

A3DGraphicsGet

Parameters:

pGraphics – [in] A handle to the entity to delete.

Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalGetGraphStyleData(const A3DUns32 uiIndexStyle, A3DGraphStyleData *pData)

Retrieves an indexed graph style.

HOOPS stores styles in a global state using indexes. When given an index, you may call A3DGlobalGetGraphStyleData to fill in an A3DGraphStyleData instance.

Version
2.0

// Retrieves the graph style at index 3. Use initialized style as default:
A3DGraphStyleData style;
A3D_INITIALIZE_DATA(A3DGraphStyleData, style);
A3DStatus result = A3DGlobalGetGraphStyleData(3, &style);
assert(result == A3D_SUCCESS);
Default style
When the input value is A3D_DEFAULT_STYLE_INDEX, pData is unchanched and the function returns immediately.

See also

A3DGlobalInsertGraphStyle

See also

A3DGraphStyleData

Parameters:
  • uiIndexStyle – [in] The index of the style to retrieve data from
  • pData – [out] The A3DGraphRgbColorData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_STYLE_INDEX – if the style index does not match any color code.
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphStyle(const A3DGraphStyleData *pData, A3DUns32 *puiIndexStyle)

Creates a new graphics style, returning its index.

When given an A3DGraphStyleData, the function searches for an already existing color code of the same value and returns its index. If the color does not exist, it is created and a new index is returned.

Version
2.0

In case of success, puiIndexRgbColor is set to the index of the color. This index can be compared to A3D_DEFAULT_COLOR_INDEX to check whether the input color code matches the default color. In case of failure *puiIndexRgbColor is unchanged.

Color Comparison
Two color codes are considered of same value when their components (red, _green and blue) have the same respective values within a tolerance of 1.0f / 255.f.

A3DGraphRgbColorData rgb;
A3D_INITIALIZE_DATA(A3DGraphRgbColorData, rgb);
rgb.m_dRed = rgb.m_dGreen = rgb.m_dBlue = 0.75f;
A3DUns32 idx_0 = A3D_DEFAULT_COLOR_INDEX;

A3DStatus result = A3DGlobalInsertGraphRgbColor(&rgb, &idx_0);
assert(result == A3D_SUCCESS);

Second insertion with the same color, expect index to be the same.
A3DUns32 idx_1 = A3D_DEFAULT_COLOR_INDEX;
result = A3DGlobalInsertGraphRgbColor(&rgb, &idx_1);
assert(result == A3D_SUCCESS);
assert(idx_0 == idx_1);

See also

A3DGlobalGetGraphRgbColorData

See also

A3DGraphRgbColorData

Parameters:
  • pData – [in] The color code to insert.
  • puiIndexStyle – [out] The resulting index for the style.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGlobalGetGraphRgbColorData(const A3DUns32 uiIndexRgbColor, A3DGraphRgbColorData *pData)

Retrieves an indexed RGB color.

HOOPS stores colors in a global state using indexes. When given an index, call A3DGlobalGetGraphRgbColorData to fill in an A3DGraphRgbColorData instance.

Version
2.0

// Retrieves the color code at index 3. Use gray shade as default color:
A3DGraphRgbColorData rgb;
A3D_INITIALIZE_DATA(A3DGraphRgbColorData, rgb);
rgb.m_dRed = rgb.m_dGreen = rgb.m_dBlue = 0.75f;
A3DStatus result = A3DGlobalGetGraphRgbColorData(3, &rgb);
assert(result == A3D_SUCCESS);
Default Color
When the input value is the index for the default color, the function returns A3D_DEFAULT_COLOR. In that case, pData is unchanged and the actual color code is up to your implementation. To support a specific default color, assign values to members of pData prior to calling A3DGlobalGetGraphRgbColorData. The default index can be explicitely stated using A3D_DEFAULT_COLOR_INDEX.
Validity
HOOPS internally stores all RGB colors in a sequential C-style array where each value is a color component: Red, Green, Blue, Red, Green, Blue, …. Thus a valid index value is either 0 or a multiple of 3.

See also

A3DGlobalInsertGraphRgbColor

See also

A3DGraphRgbColorData

Parameters:
  • uiIndexRgbColor – [in] The index of the color code
  • pData – [out] The A3DGraphRgbColorData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_DEFAULT_COLOR – if the input value is the index for the default color (A3D_DEFAULT_COLOR_INDEX).
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_COLOR_INDEX – if the color index does not match any color code.
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphRgbColor(const A3DGraphRgbColorData *pData, A3DUns32 *puiIndexRgbColor)

Creates a new indexed color, returning its index.

When given an A3DGraphRgbColorData, the function searches for an already existing color code of the same value and returns its index. If the color does not exist, it is created and a new index is returned.

Version
2.0

In case of success, puiIndexRgbColor is set to the index of the color. This index can be compared to A3D_DEFAULT_COLOR_INDEX to check whether the input color code matches the default color. In case of failure *puiIndexRgbColor is unchanged.

Color Comparison
Two color codes are considered of “same value” when their respective components (red, green and blue) have the same value within a tolerance of 1.0f / 255.f.

A3DGraphRgbColorData rgb;
A3D_INITIALIZE_DATA(A3DGraphRgbColorData, rgb);
rgb.m_dRed = rgb.m_dGreen = rgb.m_dBlue = 0.75f;
A3DUns32 idx_0 = A3D_DEFAULT_COLOR_INDEX;

A3DStatus result = A3DGlobalInsertGraphRgbColor(&rgb, &idx_0);
assert(result == A3D_SUCCESS);

Second insertion with the same color, expect index to be the same.
A3DUns32 idx_1 = A3D_DEFAULT_COLOR_INDEX;
result = A3DGlobalInsertGraphRgbColor(&rgb, &idx_1);
assert(result == A3D_SUCCESS);
assert(idx_0 == idx_1);

See also

A3DGlobalGetGraphRgbColorData

See also

A3DGraphRgbColorData

Parameters:
  • pData – [in] The color code to insert.
  • puiIndexRgbColor – [out] The resulting index for the input color.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGlobalGetGraphLinePatternData(const A3DUns32 uiIndexLinePattern, A3DGraphLinePatternData *pData)

Retrieves a line pattern descriptor.

HOOPS stores line patterns in a global state using indexes. When given an index, you may call A3DGlobalGetGraphLinePatternData to fill in an A3DGraphLinePatternData instance.

Version
2.0

// Retrieves the line pattern descriptor at index 3.
A3DGlobalGetGraphLinePatternData descriptor;
A3D_INITALIZE_DATA(A3DGlobalGetGraphLinePatternData, descriptor);
A3DGlobalGetGraphLinePatternData(3, &descriptor);
// Frees it:
A3DGlobalGetGraphLinePatternData(A3D_DEFAULT_LINEPATTERN_INDEX, &descriptor);
Memory management
Some data in A3DGraphLinePatternData are allocated from the heap upon calling A3DGlobalGetGraphLinePatternData. To free it, call the function with A3D_DEFAULT_LINEPATTERN_INDEX.

See also

A3DGraphLinePatternData

See also

A3DGlobalInsertGraphLinePattern

See also

A3DGraphStyleData

See also

A3DGraphPictureData

See also

A3DGraphicsData

Parameters:
  • uiIndexLinePattern – [in] The index of the line pattern descriptor
  • pData – [out] The A3DGraphLinePatternData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_LINEPATTERN_INDEX – if the given index is negative or corresponds to a non-existing line pattern.
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalGetGraphMaterialData(const A3DUns32 uiIndexMaterial, A3DGraphMaterialData *pData)

Retrieves an indexed RGB color.

HOOPS stores materials in a global state using indexes. When given an index, call A3DGlobalGetGraphMaterialData to fill in an A3DGraphMaterialData instance.

Version
2.0

// Retrieves the material data at index 3:
A3DGraphMaterialData material_data;
A3D_INITIALIZE_DATA(A3DGraphMaterialData, material_data);
A3DStatus result = A3DGlobalGetGraphMaterialData(3, &material_data);
assert(result == A3D_SUCCESS);

See also

A3DGlobalInsertGraphMaterial

See also

A3DGraphMaterialData

See also

A3DMiscPointerFromIndexGet

Note

This function allows getting basic material data from its index in the global state. To retrieve the underlying material entity, use A3DMiscPointerFromIndexGet as stated in the documentation for A3DGraphMaterialData

Parameters:
  • uiIndexMaterial – [in] The index of the material
  • pData – [out] The A3DGraphMaterialData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_MATERIAL_INDEX – if the material index does not match any existing.
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphMaterial(const A3DGraphMaterialData *pData, A3DUns32 *puiIndexMaterial)

Creates a new material, returning its index.

When given an A3DGraphMaterialData, the function searches for an already existing material data of the same value and returns its index. If the material does not exist, it is created and a new index is returned. In case of failure *puiIndexMaterial is unchanged.

Version
2.0

A3DGraphMaterialData material_data;
A3D_INITIALIZE_DATA(A3DGraphMaterialData, material_data);
A3DUns32 idx_0 = A3D_DEFAULT_MATERIAL_INDEX;

A3DStatus result = A3DGlobalInsertGraphMaterial(&material_data, &idx_0);
assert(result == A3D_SUCCESS);

Second insertion with the same data, expect index to be the same.
A3DUns32 idx_1 = A3D_DEFAULT_MATERIAL_INDEX;
result = A3DGlobalInsertGraphMaterial(&material_data, &idx_1);
assert(result == A3D_SUCCESS);
assert(idx_0 == idx_1);

See also

A3DGlobalGetGraphMaterialData

See also

A3DGraphMaterialData

Parameters:
  • pData – [in] The material data to insert.
  • puiIndexMaterial – [out] The resulting index for the input color.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGlobalGetGraphPictureData(const A3DUns32 uiIndexPicture, A3DGraphPictureData *pData)

Retrieves an A3DGraphPictureData instance.

HOOPS stores picture information in a global state using indexes. When given an index, call A3DGlobalGetGraphPictureData to fill in an A3DGraphPictureData instance.

Version
2.0

// Retrieves the picture data at index 3:
A3DGraphPictureData picture_data;
A3D_INITIALIZE_DATA(A3DGraphPictureData, picture_data);
A3DStatus result = A3DGlobalGetGraphPictureData(3, &picture_data);
assert(result == A3D_SUCCESS);

See also

A3DGraphPictureData

See also

A3DGlobalInsertGraphPicture

Memory management
pData contains data allocated from heap by A3DGlobalGetGraphPictureData. This data must be explicitely freed by your application. To do so, you can use the convienence call to A3DGlobalGetGraphPictureData with A3D_DEFAULT_PICTURE_INDEX: 
// Deallocating data previously reserved by A3DGlobalGetGraphPictureData:
result = A3DGlobalGetGraphPictureData(A3D_DEFAULT_PICTURE_INDEX, &picture_data);
assert(result == A3D_SUCCESS);

Parameters:
  • uiIndexPicture – [in] The index of the picture data.
  • pData – [out] The A3DGraphPictureData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_PICTURE_INDEX – if the picture index does not match any existing.
  • A3D_INVALID_PICTURE_FORMAT – if the internal image format is not supported.
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphPicture(const A3DGraphPictureData *pData, A3DUns32 *puiPictureIndex)

Insert a new picture into the global state, returning its index.

When given an A3DGraphPictureData, the function clones the picture data for internal storage and returns a new index to further retrieval with A3DGlobalGetGraphPictureData. In case of failure *puiPictureIndex is unchanged.

Version
2.0

A3DGraphPictureData picture_data;
A3D_INITIALIZE_DATA(A3DGraphPictureData, picture_data);
// Configure picture_data...
A3DUns32 idx = A3D_DEFAULT_MATERIAL_INDEX;

A3DStatus result = A3DGlobalInsertGraphPicture(&picture_data, &idx);
assert(result == A3D_SUCCESS);
assert(idx != A3D_DEFAULT_MATERIAL_INDEX);

Memory management
Upon inserting a new picture data into the the library the memory pointed to by pData->m_pucBinaryData is internally cloned. Thus, your application is only responsible for the memory management of pData.

Parameters:
  • pData – [in] The picture data to insert.
  • puiPictureIndex – [out] The resulting index for the inserted picture data.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_ERROR – when an internal error is encountered while storing the image data.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGlobalGetGraphDottingPatternData(const A3DUns32 uiIndexDottingPattern, A3DGraphDottingPatternData *pData)

Retrieves an A3DGraphDottingPatternData instance.

HOOPS stores pattern information in a global state using indexes. When given an index, call A3DGlobalGetGraphDottingPatternData to fill in an A3DGraphDottingPatternData instance.

Version
2.0

// Retrieves the picture data at index 3:
A3DGraphDottingPatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphDottingPatternData, pattern_data);
A3DStatus result = A3DGlobalGetGraphDottingPatternData(3, &pattern_data);
assert(result == A3D_SUCCESS);

See also

A3DGraphDottingPatternData

See also

A3DGlobalInsertGraphDottingPattern

See also

A3DGraphHatchingPatternData

See also

A3DGraphSolidPatternData

See also

A3DGraphVPicturePatternData

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_PATTERN_INDEX – if uiIndexDottingPattern does not match any existing.
  • A3D_BASEWITHGRAPHICS_BAD_ENTITY_TYPE – if uiIndexDottingPattern is invalid but indexes an other pattern type (either A3DGraphHatchingPatternData, A3DGraphSolidPatternData or A3DGraphVPicturePatternData)
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphDottingPattern(const A3DGraphDottingPatternData *pData, A3DUns32 *puiIndexDottingPattern)

Insert a new dotting pattern into the global state, returning its index.

When given an A3DGraphDottingPatternData, the function clones the picture data for internal storage and returns a new index to further retrieval with A3DGlobalGetGraphPictureData. In case of failure *puiIndexDottingPattern is unchanged.

Version
2.0

A3DGraphDottingPatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphDottingPatternData, pattern_data);
// Configure pattern_data...
A3DUns32 idx = A3D_DEFAULT_PATTERN_INDEX;

A3DStatus result = A3DGlobalInsertGraphDottingPattern(&pattern_data, &idx);
assert(result == A3D_SUCCESS);
assert(idx != A3D_DEFAULT_PATTERN_INDEX);

See also

A3DGraphDottingPatternData

See also

A3DGlobalGetGraphDottingPatternData

See also

A3DGraphHatchingPatternData

See also

A3DGraphSolidPatternData

See also

A3DGraphVPicturePatternData

Parameters:
  • pData – [in] The pattern data to insert.
  • puiIndexDottingPattern – [out] The resulting index for the inserted pattern data.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_ERROR – when an internal error is encountered while storing the pattern data.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGlobalGetGraphHatchingPatternData(const A3DUns32 uiIndexHatchingPattern, A3DGraphHatchingPatternData *pData)

Retrieves an A3DGraphHatchingPatternData instance.

HOOPS stores pattern information in a global state using indexes. When given an index, you may call A3DGlobalGetGraphHatchingPatternData to fill in an A3DGraphHatchingPatternData instance.

Version
2.0

// Retrieves the pattern data at index 3:
A3DGraphHatchingPatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphHatchingPatternData, pattern_data);
A3DStatus result = A3DGlobalGetGraphHatchingPatternData(3, &pattern_data);
assert(result == A3D_SUCCESS);
// Frees it:
A3DGlobalGetGraphHatchingPatternData(A3D_DEFAULT_PATTERN_INDEX, &descriptor);
Memory management
Some data in A3DGraphHatchingPatternData are allocated from the heap upon calling A3DGlobalGetGraphHatchingPatternData. To free it, call the function again with A3D_DEFAULT_PATTERN_INDEX.

See also

A3DGraphHatchingPatternData

See also

A3DGlobalInsertGraphHatchingPattern

See also

A3DGraphDottingPatternData

See also

A3DGraphSolidPatternData

See also

A3DGraphVPicturePatternData

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_PATTERN_INDEX – if uiIndexHatchingPattern does not match any existing.
  • A3D_BASEWITHGRAPHICS_BAD_ENTITY_TYPE – if uiIndexHatchingPattern is invalid but indexes an other pattern type (either A3DGraphDottingPatternData, A3DGraphSolidPatternData or A3DGraphVPicturePatternData)
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphHatchingPattern(const A3DGraphHatchingPatternData *pData, A3DUns32 *puiIndexHatchingPattern)

Insert a new hatching lines fill pattern into the global state, returning its index for further retrieval.

When given an A3DGraphHatchingPatternData, the function clones the content for internal storage and returns a new index for further retrieval with A3DGlobalGetGraphHatchingPatternData. In case of failure *puiIndexHatchingPattern is unchanged.

Version
2.0

A3DGraphHatchingPatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphHatchingPatternData, pattern_data);
// Configure pattern_data...
A3DUns32 idx = A3D_DEFAULT_PATTERN_INDEX;

A3DStatus result = A3DGlobalInsertGraphHatchingPattern(&pattern_data, &idx);
assert(result == A3D_SUCCESS);
assert(idx != A3D_DEFAULT_PATTERN_INDEX);

See also

A3DGraphHatchingPatternData

See also

A3DGraphHatchingPatternLineData

See also

A3DGlobalGetGraphHatchingPatternData

See also

A3DGraphDottingPatternData

See also

A3DGraphSolidPatternData

See also

A3DGraphVPicturePatternData

Memory management
A3DGraphHatchingPatternData contains heap allocated data. When called, A3DGlobalInsertGraphHatchingPattern will clone these data internally. Thus, your application is responsible for the management of pData only and not for the cloned content.

Parameters:
  • pData – [in] The pattern data to insert.
  • puiIndexHatchingPattern – [out] The resulting index for the inserted pattern data.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_ERROR – when an internal error is encountered while storing the pattern data.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGlobalGetGraphSolidPatternData(const A3DUns32 uiIndexSolidPattern, A3DGraphSolidPatternData *pData)

Retrieves an A3DGraphHatchingPatternData instance.

HOOPS stores pattern information in a global state using indexes. When given an index, call A3DGlobalGetGraphSolidPatternData to fill in an A3DGraphSolidPatternData instance.

Version
2.0

// Retrieves the pattern data at index 3:
A3DGraphSolidPatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphSolidPatternData, pattern_data);
A3DStatus result = A3DGlobalGetGraphSolidPatternData(3, &pattern_data);
assert(result == A3D_SUCCESS);

See also

A3DGraphDottingPatternData

See also

A3DGlobalInsertGraphHatchingPattern

See also

A3DGraphHatchingPatternData

See also

A3DGraphVPicturePatternData

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_PATTERN_INDEX – if uiIndexDottingPattern does not match any existing.
  • A3D_BASEWITHGRAPHICS_BAD_ENTITY_TYPE – if uiIndexDottingPattern is invalid but indexes an other pattern type (either A3DGraphHatchingPatternData, A3DGraphDottingPatternData or A3DGraphVPicturePatternData)
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphSolidPattern(const A3DGraphSolidPatternData *pData, A3DUns32 *puiIndexSolidPattern)

Insert a new solid fill pattern into the global state, returning its index for further retrieval.

When given an A3DGraphSolidPatternData, the function clones the content for internal storage and returns a new index for further retrieval with A3DGlobalGetGraphSolidPatternData. In case of failure *puiIndexSolidPattern is unchanged.

Version
2.0

A3DGraphSolidPatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphSolidPatternData, pattern_data);
// Configure pattern_data...
A3DUns32 idx = A3D_DEFAULT_PATTERN_INDEX;

A3DStatus result = A3DGlobalInsertGraphHatchingPattern(&pattern_data, &idx);
assert(result == A3D_SUCCESS);
assert(idx != A3D_DEFAULT_PATTERN_INDEX);

See also

A3DGraphSolidPatternData

See also

A3DGlobalGetGraphSolidPatternData

See also

A3DGraphDottingPatternData

See also

A3DGraphSolidPatternData

See also

A3DGraphVPicturePatternData

Parameters:
  • pData – [in] The pattern data to insert.
  • puiIndexSolidPattern – [out] The resulting index for the inserted pattern data.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_ERROR – when an internal error is encountered while storing the pattern data.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGlobalGetGraphVPicturePatternData(const A3DUns32 uiIndexVPicturePattern, A3DGraphVPicturePatternData *pData)

Retrieves an A3DGraphVPicturePatternData instance.

HOOPS stores pattern information in a global state using indexes. When given an index, call A3DGlobalInsertGraphVPicturePattern to fill in an A3DGraphVPicturePatternData instance.

Version
2.0

// Retrieves the pattern data at index 3:
A3DGraphVPicturePatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphVPicturePatternData, pattern_data);
A3DStatus result = A3DGlobalGetGraphVPicturePatternData(3, &pattern_data);

assert(result == A3D_SUCCESS);
Retrieve tessellation base and markup data:
if(pattern_data.m_pMarkupTess != 0) {
    A3DTessBaseData tess_base;
    A3D_INITIALIZE_DATA(A3DTessBaseData, tess_base);
    result = A3DTessBaseGet(pattern_data.m_pMarkupTess, &tess_base);
    assert(result == A3D_SUCCESS);

    A3DTessMarkupData tess_markup;
    A3D_INITIALIZE_DATA(A3DTessMarkupGet, tess_markup);
    result = A3DTessMarkupGet(pattern_data.m_pMarkupTess, &tess_markup);
    assert(result == A3D_SUCCESS);

    // ...
    A3DTessMarkupGet(0, &tess_markup);
    A3DTessBaseGet(0, &tess_base);
}
Memory management
A3DGraphVPicturePatternData contains a handle to an already existing instance of A3DTessMarkupData. This instance is entirely managed by HOOPS. Thus you are not responsible for deleting an entity returned by this function.

See also

A3DGraphVPicturePatternData

See also

A3DGlobalInsertGraphVPicturePattern

See also

A3DTessBaseGet

See also

A3DTessMarkupGet

See also

A3DTessBaseData

See also

A3DTessMarkupData

See also

A3DGraphDottingPatternData

See also

A3DGraphSolidPatternData

See also

A3DGraphVPicturePatternData

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_PATTERN_INDEX – if uiIndexVPicturePattern does not match any existing.
  • A3D_BASEWITHGRAPHICS_BAD_ENTITY_TYPE – if uiIndexVPicturePattern is invalid but indexes an other pattern type (either A3DGraphDottingPatternData, A3DGraphSolidPatternData or A3DGraphVPicturePatternData)
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGlobalInsertGraphVPicturePattern(const A3DGraphVPicturePatternData *pData, A3DUns32 *puiIndexVPicturePattern)

Insert a new vectorized picture fill pattern into the global state, returning its index for further retrieval.

When given an A3DGraphVPicturePatternData, the function clones the content for internal storage and returns a new index for further retrieval with A3DGlobalGetGraphHatchingPatternData. In case of failure *puiIndexVPicturePattern is unchanged.

Version
2.0

A3DGraphVPicturePatternData pattern_data;
A3D_INITIALIZE_DATA(A3DGraphVPicturePatternData, pattern_data);
// Configure pattern_data...
A3DUns32 idx = A3D_DEFAULT_PATTERN_INDEX;

A3DStatus result = A3DGlobalInsertGraphVPicturePattern(&pattern_data, &idx);
assert(result == A3D_SUCCESS);
assert(idx != A3D_DEFAULT_PATTERN_INDEX);

See also

A3DGraphVPicturePatternData

See also

A3DGlobalGetGraphVPicturePatternData

See also

A3DTessBaseSet

See also

A3DTessMarkupCreate

See also

A3DTessBaseData

See also

A3DTessMarkupData

See also

A3DGraphDottingPatternData

See also

A3DGraphSolidPatternData

See also

A3DGraphVPicturePatternData

Memory management
A3DGraphVPicturePatternData contains a handle to an already existing instance of A3DTessMarkupData. This instance is entirely managed by HOOPS.

Parameters:
  • pData – [in] The pattern data to insert.
  • puiIndexVPicturePattern – [out] The resulting index for the inserted pattern data.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_ERROR – when an internal error is encountered while storing the pattern data.
Returns:

A3D_SUCCESS or an error code.
A3DStatus A3DGraphCameraGet(const A3DGraphCamera *pCamera, A3DGraphCameraData *pData)

Fetches data from a camera entity given its handle. 

// Retrieves the camera data at index 3:
A3DGraphCameraData camera;
A3D_INITIALIZE_DATA(A3DGraphCameraData, camera);
A3DStatus result = A3DGraphCameraGet(3, &camera);
assert(result == A3D_SUCCESS);
Version
2.0

See also

A3DGraphCameraData

See also

A3DGraphCameraCreate

See also

A3DGraphSceneDisplayParametersData

See also

A3DAsmProductOccurrenceData

Parameters:
  • pCamera – [in] A handle to the camera to fetch data from.
  • pData – [out] The A3DGraphCameraData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphCameraCreate(const A3DGraphCameraData *pData, A3DGraphCamera **ppCamera)

Creates a new camera entity, returning its handle.

Once created, the new camera entity can be referenced to by its handle, given by *ppCamera. In case of failure, *ppCamera is unchanged.

Version
2.0

A3DGraphCamera handle = 0;
A3DGraphCameraData data;
A3D_INITIALIZE_DATA(A3DGraphCameraData, data);
// Configure data...
A3DStatus result = A3DGraphCameraCreate(&data, &handle);
assert(handle != 0);

See also

A3DGraphCameraData

See also

A3DGraphCameraGet

See also

A3DGraphSceneDisplayParametersData

See also

A3DAsmProductOccurrenceData

Memory management
Once created, entities must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DEntityDelete on it.

Parameters:
  • pData – [out] The data used for camera creation.
  • ppCamera – [in] An address to the new handle after creation.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphAmbientLightGet(const A3DGraphAmbientLight *pLight, A3DGraphAmbientLightData *pData)

Fetches data from an ambient light source entity given its handle. 

// Retrieves the light data at index 3:
A3DGraphAmbientLightData light;
A3D_INITIALIZE_DATA(A3DGraphAmbientLightData, light);
A3DStatus result = A3DGraphAmbientLightGet(3, &light);
assert(result == A3D_SUCCESS);
Version
2.0
Validity
All light sources can be interpreted as ambient if only the color is read. This is why A3DGraphAmbientLightGet can be safely called with any of the four light source types HOOPS provides.

See also

A3DGraphAmbientLightData

See also

A3DGraphAmbientLightCreate

See also

A3DGraphDirectionalLightData

See also

A3DGraphPointLightData

See also

A3DGraphSpotLightData

See also

A3DGraphSceneDisplayParametersData

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphAmbientLightCreate(const A3DGraphAmbientLightData *pData, A3DGraphAmbientLight **ppLight)

Creates a new ambient light source entity, returning its handle.

Once created, the new light entity can be referenced to by its handle, given by *ppLight. In case of failure, *ppLight is unchanged.

Version
2.0

A3DGraphAmbientLight handle = 0;
A3DGraphAmbientLightData data;
A3D_INITIALIZE_DATA(A3DGraphAmbientLightData, data);
// Configure data...
A3DStatus result = A3DGraphAmbientLightCreate(&data, &handle);
assert(handle != 0);

See also

A3DGraphAmbientLightData

See also

A3DGraphAmbientLightGet

See also

A3DGraphDirectionalLightData

See also

A3DGraphPointLightData

See also

A3DGraphSpotLightData

See also

A3DGraphSceneDisplayParametersData

Memory management
Once created, entities must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DEntityDelete on it.

Parameters:
  • pData – [out] The data used for light creation.
  • ppLight – [in] An address to the new handle after creation.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphPointLightGet(const A3DGraphPointLight *pLight, A3DGraphPointLightData *pData)

Fetches data from a point light source entity given its handle. 

// Retrieves the light data at index 3:
A3DGraphPointLightData light;
A3D_INITIALIZE_DATA(A3DGraphPointLightData, light);
A3DStatus result = A3DGraphPointLightGet(3, &light);
assert(result == A3D_SUCCESS);
Version
2.0

See also

A3DGraphPointLightData

See also

A3DGraphPointLightCreate

See also

A3DGraphAmbientLightData

See also

A3DGraphDirectionalLightData

See also

A3DGraphSpotLightData

See also

A3DGraphSceneDisplayParametersData

Parameters:
  • pLight – [in] A handle to the light to fetch data from.
  • pData – [out] The A3DGraphPointLightData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_ENTITY_TYPE – if the entity type pLight refers to is not kA3DTypeGraphPointLight
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphPointLightCreate(const A3DGraphPointLightData *pData, A3DGraphPointLight **ppLight)

Creates a new point light source entity, returning its handle.

Once created, the new light entity can be referenced to by its handle, given by *ppLight. In case of failure, *ppLight is unchanged.

Version
2.0

A3DGraphPointLight handle = 0;
A3DGraphPointLightData data;
A3D_INITIALIZE_DATA(A3DGraphPointLightData, data);
// Configure data...
A3DStatus result = A3DGraphPointLightCreate(&data, &handle);
assert(handle != 0);

See also

A3DGraphAmbientLightData

See also

A3DGraphAmbientLightGet

See also

A3DGraphDirectionalLightData

See also

A3DGraphPointLightData

See also

A3DGraphSpotLightData

See also

A3DGraphSceneDisplayParametersData

Memory management
Once created, entities must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DEntityDelete on it.

Parameters:
  • pData – [out] The data used for light creation.
  • ppLight – [in] An address to the new handle after creation.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphSpotLightGet(const A3DGraphSpotLight *pLight, A3DGraphSpotLightData *pData)

Fetches data from a spotlight source entity given its handle. 

// Retrieves the light data at index 3:
A3DGraphSpotLightData light;
A3D_INITIALIZE_DATA(A3DGraphSpotLightData, light);
A3DStatus result = A3DGraphSpotLightGet(3, &light);
assert(result == A3D_SUCCESS);
Version
2.0

See also

A3DGraphSpotLightData

See also

A3DGraphSpotLightCreate

See also

A3DGraphAmbientLightData

See also

A3DGraphDirectionalLightData

See also

A3DGraphPointLightData

See also

A3DGraphSceneDisplayParametersData

Parameters:
  • pLight – [in] A handle to the light to fetch data from.
  • pData – [out] The A3DGraphSpotLightData to fill in.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_ENTITY_TYPE – if the entity type pLight refers to is not kA3DTypeGraphSpotLight
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphSpotLightCreate(const A3DGraphSpotLightData *pData, A3DGraphSpotLight **ppLight)

Creates a new spotlight source entity, returning its handle.

Once created, the new light entity can be referenced to by its handle, given by *ppLight. In case of failure, *ppLight is unchanged.

Version
2.0

A3DGraphSpotLight handle = 0;
A3DGraphSpotLightData data;
A3D_INITIALIZE_DATA(A3DGraphSpotLightData, data);
// Configure data...
A3DStatus result = A3DGraphSpotLightCreate(&data, &handle);
assert(handle != 0);

See also

A3DGraphSpotLightData

See also

A3DGraphAmbientLightData

See also

A3DGraphAmbientLightGet

See also

A3DGraphDirectionalLightData

See also

A3DGraphPointLightData

See also

A3DGraphSceneDisplayParametersData

Memory management
Once created, entities must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DEntityDelete on it.

Parameters:
  • pData – [out] The data used for light creation.
  • ppLight – [in] An address to the new handle after creation.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphDirectionalLightGet(const A3DGraphDirectionalLight *pLight, A3DGraphDirectionalLightData *pData)

Fetches data from a directional source entity given its handle. 

// Retrieves the light data at index 3:
A3DGraphDirectionalLightData light;
A3D_INITIALIZE_DATA(A3DGraphDirectionalLightData, light);
A3DStatus result = A3DGraphDirectionalLightGet(3, &light);
assert(result == A3D_SUCCESS);
Version
2.0

See also

A3DGraphDirectionalLightData

See also

A3DGraphDirectionalLightCreate

See also

A3DGraphAmbientLightData

See also

A3DGraphDirectionalLightData

See also

A3DGraphPointLightData

See also

A3DGraphSceneDisplayParametersData

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
  • A3D_INVALID_ENTITY_TYPE – if the entity type pLight refers to is not kA3DTypeGraphDirectionalLight
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphDirectionalLightCreate(const A3DGraphDirectionalLightData *pData, A3DGraphDirectionalLight **ppLight)

Creates a new directional source entity, returning its handle.

Once created, the new light entity can be referenced to by its handle, given by *ppLight. In case of failure, *ppLight is unchanged.

Version
2.0

A3DGraphDirectionalLight handle = 0;
A3DGraphDirectionalLightData data;
A3D_INITIALIZE_DATA(A3DGraphDirectionalLightData, data);
// Configure data...
A3DStatus result = A3DGraphDirectionalLightCreate(&data, &handle);
assert(handle != 0);

See also

A3DGraphDirectionalLightData

See also

A3DGraphDirectionalLightGet

See also

A3DGraphAmbientLightData

See also

A3DGraphAmbientLightGet

See also

A3DGraphPointLightData

See also

A3DGraphSpotLightData

See also

A3DGraphSceneDisplayParametersData

Memory management
Once created, entities must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DEntityDelete on it.

Parameters:
  • pData – [out] The data used for light creation.
  • ppLight – [in] An address to the new handle after creation.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphSceneDisplayParametersGet(const A3DGraphSceneDisplayParameters *pSceneDisplayParameters, A3DGraphSceneDisplayParametersData *pData)

Fetches data from a scene diplay parameters entity given its handle. 

// Retrieves the scene display data handled by pHandle:
A3DGraphSceneDisplayParametersData data;
A3D_INITIALIZE_DATA(A3DGraphSceneDisplayParametersData, data);
A3DStatus result = A3DGraphSceneDisplayParametersGet(pHandle, &data);
assert(result == A3D_SUCCESS);
// Free the data:
A3DGraphSceneDisplayParametersGet(0, &data);
Version
2.0
Memory management
pData contains data allocated from heap by A3DGraphSceneDisplayParametersGet. This data must be explicitely freed by your application. To do so, you can use the convienence call to A3DGraphSceneDisplayParametersGet with 0 as handle.

See also

A3DGraphSceneDisplayParametersCreate

See also

A3DGraphSceneDisplayParametersData

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DGraphSceneDisplayParametersCreate(const A3DGraphSceneDisplayParametersData *pData, A3DGraphSceneDisplayParameters **ppSceneDisplayParameters)

Creates a new A3DGraphSceneDisplayParameters entity, returning its handle.

Once created, the new entity can be referenced to by its handle, given by *ppSceneDisplayParameters. In case of failure, *ppLight is unchanged.

Version
2.0

A3DGraphSceneDisplayParameters handle = 0;
A3DGraphSceneDisplayParametersData data;
A3D_INITIALIZE_DATA(A3DGraphSceneDisplayParametersData, data);
// Configure data...
A3DStatus result = A3DGraphSceneDisplayParametersCreate(&data, &handle);
assert(handle != 0);

See also

A3DGraphSceneDisplayParametersData

See also

A3DGraphSceneDisplayParametersGet

Memory management
Once created, entities must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DEntityDelete on it.

Parameters:
  • pData – [out] The data used for scene parameters creation.
  • ppSceneDisplayParameters – [in] An address to the new handle after creation.
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if pData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if pData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DMiscCascadedAttributesCreate(A3DMiscCascadedAttributes **ppAttr)

Creates a new A3DMiscCascadedAttributes entity, returning its handle.

Once created, the new entity can be referenced to by its handle, given by *ppAttr. In case of failure, *ppAttr is unchanged.

Version
2.0

A3DGraphSceneDisplayParameters handle = 0;
A3DStatus result = A3DMiscCascadedAttributesCreate(&handle);
assert(result == A3D_SUCCESS);
assert(handle != 0);

See also

A3DMiscCascadedAttributesData

See also

A3DMiscCascadedAttributesGet

See also

A3DMiscCascadedAttributesDelete

Memory management
Once created, the entity must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DMiscCascadedAttributesDelete on it.

Parameters:

ppAttr – [out] An address to the new handle after creation.

Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DMiscCascadedAttributesDelete(A3DMiscCascadedAttributes *pAttr)

Deletes a A3DMiscCascadedAttributes.

Once created with A3DMiscCascadedAttributesCreate, a cascaded attributes entity must be integrated within a model file so that HOOPS is responsible for its memory management. If the entity is created but never used, it is up to your application to request for its deletion by calling A3DMiscCascadedAttributesDelete on it.

Version
2.0

See also

A3DMiscCascadedAttributesData

See also

A3DMiscCascadedAttributesCreate

See also

A3DMiscCascadedAttributesGet

Parameters:

pAttr – [in] A handle to the entity to delete.

Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DMiscCascadedAttributesGet(const A3DMiscCascadedAttributes *pAttr, A3DMiscCascadedAttributesData *psData)

Fetches data from a cascaded attributes entity given its handle. 

// Retrieves the light data at handle 'light':
A3DMiscCascadedAttributesData data;
A3D_INITIALIZE_DATA(A3DMiscCascadedAttributesData, data);
A3DStatus result = A3DMiscCascadedAttributesGet(3, &data);
assert(result == A3D_SUCCESS);
Version
2.0

See also

A3DMiscCascadedAttributesData

See also

A3DMiscCascadedAttributesCreate

See also

A3DMiscCascadedAttributesDelete

Parameters:
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_DATA_STRUCT_NULL – if psData is null.
  • A3D_INVALID_DATA_STRUCT_SIZE – if psData is incorrectly initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DMiscCascadedAttributesPush(A3DMiscCascadedAttributes *pAttr, const A3DRootBaseWithGraphics *pBase, const A3DMiscCascadedAttributes *pFather)

Computes the result of cascaded attribute propagation from a parent node.

In the context of a model file node hierarchy, cascaded describes the way an application using HOOPS Exchange will resolve conflicting attributes. Attributes are propagated downstream, by overriding current attributes with the parent node’s ones according to specific inheritance rules defined in Bit Field for Behavior on Graphics.

Version
2.0

Although properties propagation can be manually applied if those rules are known, HOOPS Exchange provides #A3DMiscCascadedAttributesPush as a convenience function.

#A3DMiscCascadedAttributesPush computes the result of propagating attributes from pFather to pBase and writes them into pAttr, which data can then be retrieves using #A3DMiscCascadedAttributesGet.

pBase can be any instance of #A3DTopoFace #A3DTopoShell, #A3DTopoConnex, #A3DRiRepresentationItem, #A3DAsmPartDefinition or #A3DAsmProductOccurrence.

example
The following example traverses a product occurrence tree, calling A3DMiscCascadedAttributesPush on each new node: 
void traverse_product_occurrence(const A3DAsmProductOccurrence* product_occurrence, const A3DMiscCascadedAttributes* parent_attributes)
{
    // Compute new cascaded attributes entity using parent and local info
    A3DMiscCascadedAttributes* computed_attributes = 0;
    A3DMiscCascadedAttributesCreate(computed_attributes);

    A3DMiscCascadedAttributesPush(
        computed_attributes,
        product_occurrence,   // as const A3DRootBaseWithGraphics*
        parent_attributes
    );

    // Recursively call children po, giving them local computed_attributes
    A3DAsmProductOccurrenceData po_data;
    A3D_INITIALIZE_DATA(A3DAsmProductOccurrenceData, po_data);
    A3DAsmProductOccurrenceGet(product_occurrence, &po_data);

    for (size_t po = 0; po < po_data.m_uiproduct_occurrencesSize; ++po) {
        traverse_product_occurrence(po_data.m_ppproduct_occurrences[ui], computed_attributes);
    }

    A3DAsmProductOccurrenceGet(0, &po_data);
    A3DMiscCascadedAttributesDelete(computed_attributes);
}

Parameters:
  • pAttr – [in] A handle to the resulting cascaded attributes
  • pBase – [in] The child node the attributes are computed from
  • pFather – [in] The attributes held by the parent node
Return values:
  • A3D_SUCCESS – in case of success.
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
Returns:

A3D_SUCCESS or an error code in case of failure.
A3DStatus A3DMiscPointerFromIndexGet(const A3DUns32 uiIndex, const A3DEEntityType eType, A3DEntity **ppEntity)

Retrieve the handle of an indexed entity.

Even if they are usually accessed using a numerical index from the global data, entities such as A3DGraphMaterialData each have a handle like any other entity.

Version
2.0

This function allows you to retrieve the entity handle behind an indexed data. From the entity, additional content can be obtained, such as meta-data.

eType can be one of:

Supported types

Parameters:
  • uiIndex – [in] The index of the data in the global data
  • eType – [in] The expected entity type
  • ppEntity – [out] A pointer to the resulting entity handle
Returns:

A3D_SUCCESS or A3D_ERROR

A3DStatus A3DMiscRootBaseInsertAttribute(const A3DRootBase *pRootBase, const A3DMiscAttribute *pAttribute)

Adds a new attribute to the given entity.

Version
2.0

Parameters:
  • pRootBase – [in] A handle to the entity
  • pAttribute – [in] A handle to the new attribute
Return values:
  • A3D_INITIALIZE_NOT_CALLED – if the library is not initialized
  • A3D_INVALID_ENTITY_NULL – if either pRootBase of pAttribute is 0
  • A3D_BASE_BAD_ENTITY_TYPE – if pRootBase is not a root base type or derived
Returns:

A3D_SUCCESS or an error code