# 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.

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Envision for Desktop in your own language, or choose a sample question below to start a conversation:

What is HOOPS Envision for Desktop?
What are the latest release notes for HOOPS Envision for Desktop?
How do I start evaluating HOOPS Envision for Desktop?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...