cee::pt::ParticleDatasetReader

class ParticleDatasetReader

Subclassed by PtfxDatasetReader, VtpDatasetReader

Public Functions

ParticleDatasetReader()
CEE_DISALLOW_COPY_AND_ASSIGN(ParticleDatasetReader)
virtual bool open(const Str &filePath, Error *error = nullptr) = 0

Opens the given file and prepares the reader for subsequent calls to header() and getFrameData().

Subclass implementations must:

  • Parse the file header and populate mutableHeader() (frame count, bbox, scalar fields, etc.)
  • Call setReaderOpen(true) on success
  • Return true on success, false on failure

After a successful open, header() will return the metadata for the dataset.

See also

header() and getFrameData()

void close()

Closes the dataset and releases all cached data.

DatasetHeader header() const

Returns a copy of the dataset header.

std::unique_ptr<FrameData> getFrameData(size_t frameIndex, Error *error = nullptr)

Reads frame data for the given frameIndex.

Returns nullptr on error or out of range.

If error is non-null, the error code is set on failure.

See also

preloadFrames()

virtual bool setActiveScalarField(const Str &fieldName) = 0

Sets the active scalar field to the given fieldName.

Subclass implementations should:

  • Verify fieldName exists in constHeader().scalarFieldNames
  • Compute the scalar min/max range for the new field
  • Call applyActiveScalarField() with the field name and range

After a successful call, frames returned by getFrameData() will include per-particle scalar values for the specified field. Returns true if the field was found and activated.

See also

clearActiveScalarField() and applyActiveScalarField()

void clearActiveScalarField()

Clears the active scalar field so subsequent frames omit scalar data.

See also

setActiveScalarField()

void setCacheMemoryLimit(size_t maxBytes)

Sets the maximum amount of memory (in bytes) the LRU cache may consume.

size_t cacheMemoryLimit() const

Returns the current cache memory limit (in bytes)

size_t cacheCurrentMemoryBytes() const

Returns the total memory currently consumed by cached frames (in bytes)

void preloadFrames(size_t startFrame, size_t count)

Pre-reads count frames starting at startFrame into the cache for animation lookahead.

Frames that are already cached are skipped. Reading stops if the dataset is not open or the frame index is out of range. When multiple frames need loading, file I/O is parallelized across hardware threads to maximize disk throughput.

See also

getFrameData() and setCacheMemoryLimit()

void clearCache()

Clears the entire frame cache.

Protected Functions

virtual std::unique_ptr<FrameData> readFrame(size_t frameIndex, const Str &activeScalar) = 0

Reads the frame at the given frameIndex from the file.

Called by the base class on a cache miss. Subclass implementations should:

  • Read particle positions, IDs and (if activeScalar is non-empty) scalar values
  • Return a populated FrameData, or nullptr on failure
  • Compute and populate FrameData::bbox and FrameData::scalarRange for progressive bounds refinement (the base class merges these into the global header automatically)

Note

This method may be called from multiple threads concurrently (e.g. during preloadFrames()). The base class holds mutex() only for the cache lookup and insertion, not during the readFrame() call itself. If your subclass maintains shared mutable state, protect it with your own synchronization.

inline virtual void resetDerivedState()
void resetCommonState()

Resets the common reader state (open flag, header and cache)

The caller must hold mutex() before calling this method.

void applyActiveScalarField(const Str &fieldName, float rangeMin, float rangeMax, bool rangeValid)

Sets the active scalar field, range and validity flag, then invalidates the frame cache.

The caller must hold mutex() before calling this method.

std::mutex &mutex() const

Returns a reference to the internal mutex (for use in derived classes)

bool isReaderOpen() const

Returns whether the reader is currently open.

void setReaderOpen(bool open)

Sets the reader open state.

DatasetHeader &mutableHeader()

Returns a mutable reference to the dataset header (for derived class population)

const DatasetHeader &constHeader() const

Returns a const reference to the dataset header.