Package ke.ric.renderer.api

Class RenderedFrame

java.lang.Object
ke.ric.renderer.api.RenderedFrame
public final class RenderedFrame extends Object
Immutable rendered pixels and original capture/pass evidence, with optional asynchronous PNG and durable photo-map output. A raw capture allocates no maps. Pure image/evidence access remains available after the renderer closes; asynchronous output needs the owning facade and provider generation to remain active.

Use image() for final colour pixels, including composed layer treatments. Use passes() for native attachments, visibility and timings from each original pass. result() and the convenience visibility accessors are intentionally restricted to single-pass frames because one combined native visibility result would be ambiguous.

Output futures follow normal Java threading rules. Use the map consumer overloads when the result needs Bukkit operations on the server thread, and never block that thread waiting for conversion or saving. Cancelling an output propagates to its pending work; a file already atomically replaced or a completed durable save cannot be undone by cancellation.

  • Method Details

    • provenance

      public Optional<CaptureProvenance> provenance()
      Returns facts frozen during the original capture. Rendered time/weather overrides and camera reuse do not alter them.
      Returns:
      captured provenance, or empty when an older provider cannot supply it

    • effectiveCamera

      public Optional<SceneCamera> effectiveCamera()
      Returns the effective camera for this frame, including roll. During scene reuse this can differ from provenance().sourceCamera(); angles in SceneCamera are radians.
      Returns:
      the rendered camera when supplied by the provider

    • result

      public RenderResult result()
      Returns native pixels, attachments, visibility and measured timings for a single-pass frame. Layer colour, brightness and opacity are composed separately; use image() for final pixels.
      Returns:
      the original native result for the only pass
      Throws:
      IllegalStateException - if the frame has multiple passes; inspect passes() instead

    • passes

      public List<RenderPassResult> passes()
      Returns native evidence for every recipe pass in composition order. These results precede post-render colour, brightness and opacity; each preserves its own attachments and visibility.
      Returns:
      immutable ordered pass results

    • cameraCapturedNanos

      public long cameraCapturedNanos()
      Returns when this frame's camera pose was sampled, on the System.nanoTime() clock. Camera age and world-evidence age can differ during smooth scene reuse.
      Returns:
      a monotonic timestamp meaningful only within this server process

    • worldCapturedNanos

      public long worldCapturedNanos()
      Returns the first-world-evidence time, or a conservative capture-start fallback when unavailable. Reframing does not renew this timestamp. Compare with cameraCapturedNanos() to measure reuse.
      Returns:
      a monotonic timestamp meaningful only within this server process

    • publishedNanos

      public long publishedNanos()
      Returns the monotonic publication-admission time, sampled at the final lifecycle and freshness gate before output delivery. Stream reuse age is checked against this exact timestamp. Individual callbacks and map updates may occur later; this is not their time. Snapshot frames sample it during final server-thread publication. Like other frame timestamps, it is meaningful only within this server process.

    • getVisibleEntities

      public List<VisibleEntity> getVisibleEntities()
      Returns native entity identities and primary-ray pixel coverage for a single-pass frame. Names are labels, never identity keys. Coverage is native pass evidence, not inferred from post-processing or name lists; transparent contributors that do not own a primary ray are omitted.
      Returns:
      immutable visible-entity records
      Throws:
      IllegalStateException - if multiple passes make one visibility list ambiguous
      RendererException - with UNSUPPORTED_CAPABILITY if an older provider lacks entity identities

    • getVisiblePlayers

      public List<VisibleEntity> getVisiblePlayers()
      Returns single-pass visible entity records whose captured type is minecraft:player.
      Returns:
      an immutable list of player identities and primary-ray coverage
      Throws:
      IllegalStateException - for a multi-pass frame
      RendererException - if the provider lacks entity identities

    • toBufferedImage

      public BufferedImage toBufferedImage()
      Copies the final composed RGBA pixels into a new mutable BufferedImage. This pure conversion does not allocate maps and remains usable after renderer close. It is synchronous; perform large conversions on a worker executor. Modifying the returned image does not alter this frame.
      Returns:
      a newly allocated image preserving final RGBA alpha

    • image

      public BufferedImage image()
      Copies final composed pixels into a new BufferedImage; equivalent to toBufferedImage().
      Returns:
      a new independently mutable image; large conversions should run on a worker executor

    • savePng

      public CompletableFuture<Path> savePng(Path destination)
      Encodes final pixels and atomically replaces the destination PNG on a bounded conversion worker. The parent directory must already exist and support atomic replacement. Cancellation interrupts pending encoding/I/O; a completed replacement cannot be revoked.
      Parameters:
      destination - file path to create or replace
      Returns:
      a future completing with the supplied path only after atomic saving succeeds
      Throws:
      NullPointerException - if destination is null

    • toMapItem

      public CompletableFuture<org.bukkit.inventory.ItemStack> toMapItem()
      Fits final pixels into one 128×128 map with black aspect-preserving letterboxing, then saves a durable provider-owned photo. Conversion and disk persistence run off-thread; Bukkit map allocation runs on the server thread. Uses no dithering by default.
      Returns:
      a future for the tagged map item, completed only after saving succeeds

    • toMapItem

      public CompletableFuture<org.bukkit.inventory.ItemStack> toMapItem(MapOutputOptions options)
      Converts final pixels to one aspect-fitted 128×128 map using the chosen palette dither, then saves a durable provider-owned photo. Each call requests a photo; ordinary future callbacks have no server-thread guarantee. Your plugin owns delivery and inventory-full policy.
      Parameters:
      options - immutable map conversion settings
      Returns:
      a future for the tagged item, completed only after successful persistence
      Throws:
      NullPointerException - if options is null

    • toMapItem

      public CompletableFuture<org.bukkit.inventory.ItemStack> toMapItem(Consumer<org.bukkit.inventory.ItemStack> success)
      Saves a durable photo before delivering its item on the server thread. Lifecycle is checked before delivery; callback exceptions fail the returned future. Your plugin retains or delivers the item and handles inventory capacity.
      Parameters:
      success - nonnull server-thread consumer of the saved photo item
      Returns:
      a cancellable future settled after callback delivery

    • toMapItem

      public CompletableFuture<org.bukkit.inventory.ItemStack> toMapItem(Consumer<org.bukkit.inventory.ItemStack> success, Consumer<Throwable> error)
      Saves a durable photo before delivering its item on the server thread. Lifecycle is checked before delivery; callback exceptions fail the returned future. Your plugin retains or delivers the item and handles inventory capacity.
      Parameters:
      success - nonnull server-thread consumer of the saved photo item
      error - optional server-thread failure observer, or null; the future still fails
      Returns:
      a cancellable future settled after callback delivery

    • toMapItem

      public CompletableFuture<org.bukkit.inventory.ItemStack> toMapItem(MapOutputOptions options, Consumer<org.bukkit.inventory.ItemStack> success)
      Saves a durable photo before delivering its item on the server thread. Lifecycle is checked before delivery; callback exceptions fail the returned future. Your plugin retains or delivers the item and handles inventory capacity.
      Parameters:
      options - immutable palette conversion settings
      success - nonnull server-thread consumer of the saved photo item
      Returns:
      a cancellable future settled after callback delivery

    • toMapItem

      public CompletableFuture<org.bukkit.inventory.ItemStack> toMapItem(MapOutputOptions options, Consumer<org.bukkit.inventory.ItemStack> success, Consumer<Throwable> error)
      Saves a durable photo before delivering its item on the server thread. Lifecycle is checked before delivery; callback exceptions fail the returned future. Your plugin retains or delivers the item and handles inventory capacity.
      Parameters:
      options - immutable palette conversion settings
      success - nonnull server-thread consumer of the saved photo item
      error - optional server-thread failure observer, or null; the future still fails
      Returns:
      a cancellable future settled after callback delivery