Class SceneViewport

java.lang.Object
net.ixdarklord.coolcatcanvas.api.client.viewport.SceneViewport
All Implemented Interfaces:
AutoCloseable
@Experimental public final class SceneViewport extends Object implements AutoCloseable
A small 3D scene drawn to a texture of its own: blocks, whole structures, entities and items' icons, seen from a camera that circles them. Because it is a texture, what it shows is always kept inside the rectangle it is drawn in, wherever that is: a GUI (SceneViewportWidget), or a face in the world (use texture() with any textured render type). 
SceneViewport view = SceneViewport.create(MyMod.id("altar_view"), 256, 256);
view.block(BlockPos.ZERO, Blocks.BEACON.defaultBlockState()).camera(35, 28).spin(16);
// every frame it is on screen:
view.use();
It is drawn only when it has to be: when its scene or camera has changed, or, while it spins or holds entities (which move), a set number of times a second (refreshRate). A viewport nobody has used for a couple of seconds is not drawn at all. Everything in it is lit as the world lights it: a block's top brightest, each side its own shade, whichever way the scene is turned. The texture is upside down, as every texture drawn to is: show it with its V flipped (the widget does). Client code only; make and change viewports on the render thread.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    SceneViewport.PlacedBlock
    A block of the scene.
    static final record 
    SceneViewport.PlacedEntity
    An entity of the scene: never in a world, only drawn.
    static final record 
    SceneViewport.PlacedItem
    An item of the scene, drawn as its icon is in an inventory: size across, its middle at a place, flat to the camera when the camera looks straight on (camera(0, 0)).
    static final record 
    SceneViewport.PlacedText
    A line of text laid flat on the picture, in the texture's own pixels: its top left at (x, y), each font pixel scale texture pixels.

  • Method Summary

    Modifier and Type
    Method
    Description
    SceneViewport
    block(net.minecraft.core.BlockPos pos, net.minecraft.world.level.block.state.BlockState state)
     
    List<SceneViewport.PlacedBlock>
    blocks()
     
    SceneViewport
    blocks(Map<net.minecraft.core.BlockPos, net.minecraft.world.level.block.state.BlockState> all)
    A structure, or any build: every block of it.
    net.minecraft.world.phys.AABB
    bounds()
    The box the scene fills: what the camera circles and fits in view.
    SceneViewport
    camera(float yaw, float pitch)
    Where the camera stands about the scene, in degrees: yaw round it, pitch above it (0 level, 90 overhead).
    SceneViewport
    clear()
     
    SceneViewport
    clearText()
    Takes away the text laid on the picture, leaving the scene.
    void
    close()
    Frees the texture.
    static SceneViewport
    create(net.minecraft.resources.Identifier texture, int width, int height)
     
    List<SceneViewport.PlacedEntity>
    entities()
     
    SceneViewport
    entity(net.minecraft.world.entity.Entity entity, double x, double y, double z, float yaw)
    An entity standing with its feet at a place.
    SceneViewport
    frame(double span, double x, double y, double z)
    Fixes what the picture shows, in place of fitting the scene to it: span of the scene's own units across the picture's width, with a point of the scene at its middle.
    net.minecraft.world.phys.Vec3
    frameCentre()
     
    double
    frameSpan()
     
    SceneViewport
    ground(double y, int margin, int floorArgb, int lineArgb, boolean shadows)
    A ground under the scene at a height, turning with it: a floor in a colour, as large as the whole blocks the scene stands over and margin blocks more each way, a grid of lines on it at the block edges in another colour (both ARGB, their alpha how strong they are; 0 for none), and, with shadows, a soft shadow under each entity, as wide as the entity.
    int
    groundCells()
     
    int
    groundColor()
     
    int
    groundFloor()
     
    boolean
    groundShadows()
     
    double
    groundY()
     
    boolean
    hasGround()
     
    int
    height()
     
    boolean
    isClosed()
     
    boolean
    isReady()
    Whether the viewport has been drawn at least once, so that its texture exists: it is, from the frame after it is first used.
    SceneViewport
    item(net.minecraft.world.item.ItemStack stack, double x, double y, double z, float size)
    An item's icon.
    List<SceneViewport.PlacedItem>
    items()
     
    long
    lastUsed()
     
    SceneViewport
    noGround()
    Takes the ground away.
    float
    pitch()
     
    void
    refresh()
    Has the viewport drawn again though nothing of its own changed: a block's model, or an entity, did.
    int
    refreshRate()
     
    SceneViewport
    refreshRate(int timesPerSecond)
    How many times a second a viewport that moves (it spins, or has entities) is drawn again.
    float
    spin()
     
    SceneViewport
    spin(float degreesPerSecond)
    Turns the camera round the scene by itself, this many degrees a second; 0 to stop.
    boolean
    takeDirty()
    Whether the scene or camera has changed since it was last drawn; asking clears it.
    SceneViewport
    text(net.minecraft.util.FormattedCharSequence text, float x, float y, int color, float scale)
    A line of text laid flat on the picture (SceneViewport.PlacedText).
    List<SceneViewport.PlacedText>
    texts()
     
    net.minecraft.resources.Identifier
    texture()
     
    void
    use()
    Says the viewport is being shown this frame.
    int
    width()
     
    float
    yaw()
     
    float
    zoom()
     
    SceneViewport
    zoom(float zoom)
    How large the scene is drawn: 1 fits all of it in view from any side.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • create

      public static SceneViewport create(net.minecraft.resources.Identifier texture, int width, int height)
      Parameters:
      texture - the id its texture is registered under, for drawing it
      width - the texture's size in pixels: what it is drawn at is up to whoever draws it
      Throws:
      IllegalArgumentException - if a viewport already has that id

    • texture

      public net.minecraft.resources.Identifier texture()

    • width

      public int width()

    • height

      public int height()

    • clear

      public SceneViewport clear()

    • text

      public SceneViewport text(net.minecraft.util.FormattedCharSequence text, float x, float y, int color, float scale)
      A line of text laid flat on the picture (SceneViewport.PlacedText). A picture of nothing but text is drawn once, as sharp as its texture is large: so text can be shown as a texture, to be cut, stretched or bent with what it is on.

    • clearText

      public SceneViewport clearText()
      Takes away the text laid on the picture, leaving the scene.

    • texts

      public List<SceneViewport.PlacedText> texts()

    • block

      public SceneViewport block(net.minecraft.core.BlockPos pos, net.minecraft.world.level.block.state.BlockState state)

    • blocks

      public SceneViewport blocks(Map<net.minecraft.core.BlockPos, net.minecraft.world.level.block.state.BlockState> all)
      A structure, or any build: every block of it.

    • entity

      public SceneViewport entity(net.minecraft.world.entity.Entity entity, double x, double y, double z, float yaw)
      An entity standing with its feet at a place. It is drawn as it is each time the viewport is: animate it by ticking it.

    • item

      public SceneViewport item(net.minecraft.world.item.ItemStack stack, double x, double y, double z, float size)
      An item's icon. A scene of icons is a picture of them: look straight on with camera(0, 0) and no spin, and it is drawn once. They are lit as the game lights icons in its screens.

    • items

      public List<SceneViewport.PlacedItem> items()

    • frame

      public SceneViewport frame(double span, double x, double y, double z)
      Fixes what the picture shows, in place of fitting the scene to it: span of the scene's own units across the picture's width, with a point of the scene at its middle. For laying a scene out to match something drawn about it (a grid's frames, say). A span of 0 goes back to fitting.

    • frameSpan

      @Internal public double frameSpan()

    • frameCentre

      @Internal public net.minecraft.world.phys.Vec3 frameCentre()

    • blocks

      public List<SceneViewport.PlacedBlock> blocks()

    • entities

      public List<SceneViewport.PlacedEntity> entities()

    • bounds

      public net.minecraft.world.phys.AABB bounds()
      The box the scene fills: what the camera circles and fits in view.

    • ground

      public SceneViewport ground(double y, int margin, int floorArgb, int lineArgb, boolean shadows)
      A ground under the scene at a height, turning with it: a floor in a colour, as large as the whole blocks the scene stands over and margin blocks more each way, a grid of lines on it at the block edges in another colour (both ARGB, their alpha how strong they are; 0 for none), and, with shadows, a soft shadow under each entity, as wide as the entity.

    • noGround

      public SceneViewport noGround()
      Takes the ground away.

    • hasGround

      @Internal public boolean hasGround()

    • groundY

      @Internal public double groundY()

    • groundCells

      @Internal public int groundCells()

    • groundColor

      @Internal public int groundColor()

    • groundFloor

      @Internal public int groundFloor()

    • groundShadows

      @Internal public boolean groundShadows()

    • camera

      public SceneViewport camera(float yaw, float pitch)
      Where the camera stands about the scene, in degrees: yaw round it, pitch above it (0 level, 90 overhead).

    • zoom

      public SceneViewport zoom(float zoom)
      How large the scene is drawn: 1 fits all of it in view from any side.

    • spin

      public SceneViewport spin(float degreesPerSecond)
      Turns the camera round the scene by itself, this many degrees a second; 0 to stop.

    • refreshRate

      public SceneViewport refreshRate(int timesPerSecond)
      How many times a second a viewport that moves (it spins, or has entities) is drawn again. 60 by default, which turns smoothly; lower it for a large scene that need not.

    • yaw

      public float yaw()

    • pitch

      public float pitch()

    • zoom

      public float zoom()

    • spin

      public float spin()

    • refreshRate

      public int refreshRate()

    • use

      public void use()
      Says the viewport is being shown this frame. Without it for a couple of seconds, the viewport stops being drawn.

    • isReady

      public boolean isReady()
      Whether the viewport has been drawn at least once, so that its texture exists: it is, from the frame after it is first used.

    • refresh

      public void refresh()
      Has the viewport drawn again though nothing of its own changed: a block's model, or an entity, did.

    • close

      public void close()
      Frees the texture. The viewport draws nothing after this.
      Specified by:
      close in interface AutoCloseable

    • isClosed

      public boolean isClosed()

    • lastUsed

      @Internal public long lastUsed()

    • takeDirty

      @Internal public boolean takeDirty()
      Whether the scene or camera has changed since it was last drawn; asking clears it.