GetArea

This function calculates the area of an instance.
For perfomance reasons it is benefitial to call it with vertex and index buffer when the arrays are calculated anyway or Volume and Area are needed.

There are two ways to call GetVolume:
  vertexBuffer and indexBuffer are both zero: in this case the instance will be
    recalculated when needed. It is expected the client does not
    need the arrays itself or there is no performance issue.
  vertexBuffer and indexBuffer are both given: the call is placed directly after
    updateBuffer calls and no structural change to depending instances have
    been done in between. The transformationMatrix array is not needed,
    even if it is being used due to not giving any performance gain to this
    operation.

Note: internally the call does not store its results, any optimization based on known
    dependancies between instances need to be implemented on the client.
Note: in case precision is important and vertex buffer is 32 bit it is advised to
    set vertexBuffer and indexBuffer to 0 even if arrays are existing.

Syntax

//
//   Strong typing definition
//
double          GetArea(
                        OwlInstance             owlInstance,
                        const void              * vertexBuffer,
                        const void              * indexBuffer
                    );

static  inline  double  GetArea(
                                OwlInstance             owlInstance
                            )
{
    const void * vertexBuffer = nullptr,
                * indexBuffer = nullptr;
    return  GetArea(
                    owlInstance,
                    vertexBuffer,
                    indexBuffer
                );
}


//
//   Weak typing definition
//
double  __declspec(dllexport) __stdcall GetArea(
                                                int64_t                 owlInstance,
                                                const void              * vertexBuffer,
                                                const void              * indexBuffer
                                            );

static  inline  double  GetArea(
                                int64_t                 owlInstance
                            )
{
    const void * vertexBuffer = nullptr,
                * indexBuffer = nullptr;
    return  GetArea(
                    owlInstance,
                    vertexBuffer,
                    indexBuffer
                );
}
    

Property owlInstance

Size: 64 bit / 8 byte (value)
The handle to the specific instance in the design tree. The instance handle is static within one open model but is most probably different when the same instance is opened in another model. The instance is always exactly of one unique class.

Property vertexBuffer

Size: 32 bit / 4 byte (reference)
The array of vertices, this array is allocated by the host application. Depending on SetFormat() the array exists of 32 bit (4 byte) single precision floats or 64 bit (8 byte) double precision floats. Each vertex elements exists of several elemens, i.e. X, Y, Z values, but optionally also nX, nY, nZ, texture coordinates, bitangent / binormal coordinates, colors etc. What is contained is defined by SetFormat() and can be retrieved via GetFormat(). The host application has to make sure enough memory is allocated for the vertexBuffer array.

Property indexBuffer

Size: 32 bit / 4 byte (reference)
The array of indices, this array is allocated by the host application. Depending on SetFormat() the array exists of 32 bit (4 byte) integers or 64 bit (8 byte) integeres.

Example (based on pure API calls)

Here you can find code snippits that show how the API call GetArea can be used.

#include    "./include/engine.h"
#include    <assert.h>

void    main()
{
    int64_t model = CreateModel();

    if (model) {
        //
        //  Classes
        //
        int64_t classBox = GetClassByName(model, "Box");

        //
        //  Datatype Properties (attributes)
        //
        int64_t propertyLength = GetPropertyByName(model, "length"),
                propertyWidth = GetPropertyByName(model, "width"),
                propertyHeight = GetPropertyByName(model, "height");

        //
        //  Instances (creating)
        //
        int64_t instanceBox = CreateInstance(classBox, nullptr);

        double  length = 2.8,
                width = 1.3,
                height = 1.4;

        SetDatatypeProperty(instanceBox, propertyLength, &length, 1);
        SetDatatypeProperty(instanceBox, propertyWidth, &width, 1);
        SetDatatypeProperty(instanceBox, propertyHeight, &height, 1);

        //
        //  Simple use of the derived information functions
        //
        double  volume = GetVolume(instanceBox, nullptr, nullptr),
                area = GetArea(instanceBox, nullptr, nullptr),
                perimeter = GetPerimeter(instanceBox);

        int64_t vertexBufferSize = 0,
                indexBufferSize = 0;
        CalculateInstance(instanceBox, &vertexBufferSize, &indexBufferSize, 0);
        if (vertexBufferSize && indexBufferSize) {
            float   * vertexBuffer = new float[6 * vertexBufferSize];
            UpdateInstanceVertexBuffer(instanceBox, vertexBuffer);

            int32_t * indexBuffer = new int32_t[indexBufferSize];
            UpdateInstanceIndexBuffer(instanceBox, indexBuffer);

            //
            //  Reuse knowledge to improve performance (in case of single precision, with less accuracy)
            //
            volume = GetVolume(instanceBox, vertexBuffer, indexBuffer);
            area = GetArea(instanceBox, vertexBuffer, indexBuffer);
        }

        //
        //  The resulting model can be viewed in 3D-Editor.exe
        //
        SaveModel(model, "c:\\created\\myFile.bin");
        CloseModel(model);
    }
}