Package com.victorvalentim.zividomelive.performance

Interface PerformanceSnapshot

public interface PerformanceSnapshot
Read-only report of retained performance samples.

This is Experimental API. Snapshots are created by the runtime and obtained through ziviDomeLive.getPerformanceSnapshot().

A snapshot is immutable. Creating one allocates and sorts retained sample copies, so obtain it outside the interval being measured.

API stability: Experimental.

Since:
2.0.0

  • Method Details

    • getRequestedMode

      PerformanceMode getRequestedMode()
      Returns:
      profiling mode requested when this collection session was enabled

    • getEffectiveMode

      PerformanceMode getEffectiveMode()
      Returns:
      mode effectively used after runtime capability fallback

    • getTotalFrames

      long getTotalFrames()
      Returns:
      completed frames since the latest statistics reset, including overwritten frames

    • getStoredFrames

      int getStoredFrames()
      Returns:
      chronological frames retained by the configured ring-buffer capacity

    • getOverwrittenFrames

      long getOverwrittenFrames()
      Returns:
      completed frames displaced from the bounded ring buffer

    • getStatistics

      PerformanceSnapshot.MetricStatistics getStatistics(PerformanceMetric metric)
      Aggregates CPU-observed values for one metric over retained frames.
      Parameters:
      metric - non-null metric
      Returns:
      immutable aggregate statistics
      Throws:
      IllegalArgumentException - when metric is null

    • getGpuStatistics

      PerformanceSnapshot.MetricStatistics getGpuStatistics(PerformanceMetric metric)
      Aggregates GPU values for one metric over retained frames. Metrics without GPU instrumentation return an empty aggregate, never CPU values.
      Parameters:
      metric - non-null metric
      Returns:
      immutable GPU aggregate statistics
      Throws:
      IllegalArgumentException - when metric is null

    • hasGpuTimings

      boolean hasGpuTimings()
      Returns:
      whether at least one retained render-pipeline GPU sample is available

    • getDurationNanos

      long getDurationNanos(PerformanceMetric metric, int frameIndex)
      Parameters:
      metric - non-null sampled metric
      frameIndex - zero-based chronological retained-frame index
      Returns:
      CPU-observed duration in nanoseconds; zero means no recorded duration
      Throws:
      IllegalArgumentException - when metric is null
      IndexOutOfBoundsException - when frameIndex is not retained

    • getCalls

      int getCalls(PerformanceMetric metric, int frameIndex)
      Parameters:
      metric - non-null sampled metric
      frameIndex - zero-based chronological retained-frame index
      Returns:
      calls recorded for that metric and frame
      Throws:
      IllegalArgumentException - when metric is null
      IndexOutOfBoundsException - when frameIndex is not retained

    • getGpuDurationNanos

      long getGpuDurationNanos(PerformanceMetric metric, int frameIndex)
      Parameters:
      metric - non-null sampled metric
      frameIndex - zero-based chronological retained-frame index
      Returns:
      GPU duration in nanoseconds; zero may mean unavailable rather than zero GPU cost
      Throws:
      IllegalArgumentException - when metric is null
      IndexOutOfBoundsException - when frameIndex is not retained

    • getGpuCalls

      int getGpuCalls(PerformanceMetric metric, int frameIndex)
      Parameters:
      metric - non-null sampled metric
      frameIndex - zero-based chronological retained-frame index
      Returns:
      GPU results recorded for the frame; zero means unavailable
      Throws:
      IllegalArgumentException - when metric is null
      IndexOutOfBoundsException - when frameIndex is not retained

    • getInvariantViolations

      long getInvariantViolations()
      Returns:
      total render-graph invariant violations detected in the collection session

    • getCubemapCaptureViolations

      long getCubemapCaptureViolations()
      Returns:
      cubemap-capture invariant violations detected in the collection session

    • getUnexpectedPassViolations

      long getUnexpectedPassViolations()
      Returns:
      unexpected render-pass violations detected in the collection session

    • getDiagnostics

      List<String> getDiagnostics()
      Returns:
      immutable human-readable collection diagnostics

    • getGpuTimerPolicy

      GpuTimerPolicy getGpuTimerPolicy()
      Returns:
      GPU timer ownership and fallback policy requested for the session

    • getGpuTimerBackend

      GpuTimerBackend getGpuTimerBackend()
      Returns:
      GPU measurement backend effectively used, or GpuTimerBackend.NONE

    • getGpuTimerArchitecture

      GpuTimerArchitecture getGpuTimerArchitecture()
      Returns:
      normalized host/renderer architecture recorded during backend selection