.. _particle-writer-page:

##################
Writing PTFX Files
##################

The :class:`PtfxDatasetWriter <cee::pt::PtfxDatasetWriter>` allows you to convert simulation output into the PTFX binary
format for efficient playback:

.. code-block:: cpp

    #include "CeeParticleModel/PtfxDatasetWriter.h"

    cee::pt::PtfxDatasetWriter writer;
    cee::pt::Error error;

    std::vector<cee::pt::PtfxScalarFieldInfo> scalarFields = {
        {"Temperature", 273.0f, 1500.0f},
        {"Pressure",    0.0f,   101325.0f}
    };

    if (!writer.open("output.ptfx",
                     /*maxParticleCount=*/10000,
                     /*timestepCount=*/200,
                     /*bboxMin=*/{-1.0f, -1.0f, -1.0f},
                     /*bboxMax=*/{1.0f, 1.0f, 1.0f},
                     scalarFields,
                     &error))
    {
        // Handle error
    }

    for (size_t frame = 0; frame < 200; ++frame)
    {
        std::vector<uint32_t> ids = /* ... */;
        std::vector<float> positions = /* interleaved x,y,z ... */;
        std::vector<std::vector<float>> scalars = /* one vector per field ... */;

        writer.writeFrame(ids, positions, scalars, &error);
    }

    writer.close(&error);

You can query the writer state during the write process:

.. code-block:: cpp

    if (writer.isOpen())
    {
        size_t written = writer.framesWritten();  // Number of frames written so far
    }

The writer produces a directory structure with a header file and one binary frame file per timestep. The
:class:`PtfxScalarFieldInfo <cee::pt::PtfxScalarFieldInfo>` struct defines the name and pre-computed min/max range for
each scalar field.
