iOutputStream

Contents, API Reference, Interfaces, iOutputStream

Interface iOutputStream

Description

The client application creates objects derived from this interface to receive streamed data from PathEngine.

Defined in SDKRoot/code/externalAPI/i_pathengine.h.

#ifndef I_OUTPUTSTREAM_HAS_BEEN_INCLUDED
#define I_OUTPUTSTREAM_HAS_BEEN_INCLUDED
class iOutputStream
{
public:
    virtual ~iOutputStream() {};
    virtual void put(const char* data, uint32_t data_size)=0;
};
#endif

Methods:

put

This method is called by PathEngine to send data to an application defined output stream.

Example implementation

A very simple sample implementation of this interface for output to a file is as follows:

#include "i_pathengine.h"
#include <stdio.h>
#include <assert.h>

class cFileOutputStream : public iOutputStream
{
    FILE* _file;

public:

    cFileOutputStream(const char* name)
    {
        _file = fopen(name, "wb");
        assert(_file);
    }
    ~cFileOutputStream()
    {
        int errorOccurred = fclose(_file);
        assert(!errorOccurred);
    }
    void put(const char* data, uint32_t dataSize)
    {
        size_t written = fwrite(data, 1, dataSize, _file);
        assert(written == dataSize);
        //... the following can be added if you need to make sure that the data is not truncated by a crash
        //... but this can then have a significant effect on the final save times
        //int flushResult = fflush(_file);
        //assertR(flushResult == 0);
    }
};

Note the commented out fflush() call in the above code.
This relates to situations such as the following:

cFileOutputStream fos("..\\resource\\contentProcessing3DDemo.tok");
    gCP3D->saveSnapshot(
        VectorBuffer(meshInstances), SizeL(meshInstances),
        &allSolidObjects,
        extrudeHeight,
        maxStepHeight,
        maxSlope,
        options,
        "tok", &fos
        );
    iMesh* mesh = gCP3D->buildGround(
            VectorBuffer(meshInstances), SizeL(meshInstances),
            &allSolidObjects,
            extrudeHeight,
            maxStepHeight,
            maxSlope,
            options,
            progressCallBack
            );

The snapshot save here enables us to quickly send in all the relevant info, for example, in case there is some problem to report with regards to the following 3D processing call.

But, if the 3D processing call crashes, or hangs, or is interrupted by the debugger, then maybe the snapshot data is still being bufferred by the file subsystem at that point and not yet commited to disk.

Adding the fflush call to the output stream would be one way to avoid this problem, but a more efficient solution is to actually manage the scope of the output stream object so that the file object is closed before the 3D processing call starts, as follows:

{
        cFileOutputStream fos("..\\resource\\contentProcessing3DDemo.tok");
        gCP3D->saveSnapshot(
            VectorBuffer(meshInstances), SizeL(meshInstances),
            &allSolidObjects,
            extrudeHeight,
            maxStepHeight,
            maxSlope,
            options,
            "tok", &fos
            );
    } // ** the output stream object goes out of scope at this point, forcing the file close **
    iMesh* mesh = gCP3D->buildGround(
            VectorBuffer(meshInstances), SizeL(meshInstances),
            &allSolidObjects,
            extrudeHeight,
            maxStepHeight,
            maxSlope,
            options,
            progressCallBack
            );

next: iOutputStream::put()