Class SpriteRenderer

java.lang.Object
com.codename1.gaming.SpriteRenderer
All Implemented Interfaces:
Renderer
public class SpriteRenderer extends Object implements Renderer

Draws a Scene of Sprites on the GPU, implementing the com.codename1.gpu com.codename1.gpu.Renderer contract so it can be hosted in a com.codename1.gpu.RenderView (which GameView does for you).

Each frame it sets up an orthographic camera that maps one world unit to one pixel with the origin at the top left and y pointing down, then draws every visible sprite as a textured quad: a shared unit quad mesh scaled/rotated/ translated by a per sprite model matrix, with a com.codename1.gpu.Material.Type#SPRITE material (alpha blended, depth test off) whose texture is the sprite's image and whose color is the sprite's tint. Images are uploaded to com.codename1.gpu.Textures lazily and cached.

Use it directly for a custom host, or let GameView create and drive one:

SpriteRenderer r = new SpriteRenderer();
r.getScene().add(mySprite);
RenderView view = new RenderView(r).setContinuous(true);
form.add(BorderLayout.CENTER, view);

  • Constructor Summary

    Constructors
    Constructor
    Description
    SpriteRenderer()
    Creates a renderer with a fresh empty Scene.
    SpriteRenderer(Scene scene)
    Creates a renderer drawing the given scene.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addModel(Model model)
    Adds a 3D model to be drawn (in perspective mode) alongside the sprites.
    GameCamera
    getCamera()
    The camera this renderer draws through.
    int
    getClearColor()
     
    Light
    getLight()
    The directional light used to shade lit 3D Models.
    int
    getModelCount()
    The number of 3D models in this renderer.
    Scene
    getScene()
    The scene this renderer draws; add and remove sprites here.
    int
    getTextureCount()
    The number of images this renderer holds a texture for at the moment: those drawn since the device was created and not released since.
    void
    onDispose(GraphicsDevice device)
    Invoked when the GPU context is being torn down (for example when the view is removed from the UI).
    void
    onFrame(GraphicsDevice device)
    Invoked once per frame to render the scene.
    void
    onInit(GraphicsDevice device)
    Invoked once after the GPU context and its GraphicsDevice have been created and are current.
    void
    onResize(GraphicsDevice device, int width, int height)
    Invoked when the drawable surface size changes, including once after initialization.
    void
    releaseTexture(Image image)
    Releases the texture this renderer keeps for an image, and forgets the image.
    void
    removeModel(Model model)
    Removes a previously added 3D model.
    void
    setClearColor(int argb)
    The ARGB color the framebuffer is cleared to each frame.

    Methods inherited from class Object

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

  • Constructor Details

    • SpriteRenderer

      public SpriteRenderer()
      Creates a renderer with a fresh empty Scene.

    • SpriteRenderer

      public SpriteRenderer(Scene scene)
      Creates a renderer drawing the given scene.

  • Method Details

    • getScene

      public Scene getScene()
      The scene this renderer draws; add and remove sprites here.

    • getCamera

      public GameCamera getCamera()
      The camera this renderer draws through. Leave it in its default 2D mode for a classic sprite game, or put it in GameCamera#MODE_PERSPECTIVE to render the sprites as billboards in a 3D world.

    • getLight

      public Light getLight()
      The directional light used to shade lit 3D Models. Configure it with com.codename1.gpu.Light#setDirection(float, float, float) etc.

    • addModel

      public void addModel(Model model)
      Adds a 3D model to be drawn (in perspective mode) alongside the sprites.

    • removeModel

      public void removeModel(Model model)
      Removes a previously added 3D model.

    • getModelCount

      public int getModelCount()
      The number of 3D models in this renderer.

    • releaseTexture

      public void releaseTexture(Image image)

      Releases the texture this renderer keeps for an image, and forgets the image.

      The renderer uploads every image a sprite is drawn with once, and keeps the texture until it is disposed itself. That is right for the art of a game, and wrong for an image that is made, shown for a while and never shown again -- a text painted into an image, a generated frame: each one would hold its texture, and the image with it, for as long as the view lives. Call this when such an image is no longer drawn.

      The GPU is not touched here, since only a renderer callback has the device: the texture is disposed at the start of the next frame, before anything is drawn. So it may be called from the frame itself (GameView's update), and an image released and drawn again -- in the same frame or any later one -- is simply uploaded again. An image the renderer has no texture for, or null, is ignored.

      Like every change to the scene, it belongs on the thread that runs the frame.

      Parameters
      • image: the image whose texture is no longer needed

    • getTextureCount

      public int getTextureCount()
      The number of images this renderer holds a texture for at the moment: those drawn since the device was created and not released since.

    • setClearColor

      public void setClearColor(int argb)
      The ARGB color the framebuffer is cleared to each frame.

    • getClearColor

      public int getClearColor()

    • onInit

      public void onInit(GraphicsDevice device)
      Description copied from interface: Renderer

      Invoked once after the GPU context and its GraphicsDevice have been created and are current. Allocate buffers, textures and materials here.

      Parameters
      • device: the graphics device bound to this view
      Specified by:
      onInit in interface Renderer

    • onResize

      public void onResize(GraphicsDevice device, int width, int height)
      Description copied from interface: Renderer

      Invoked when the drawable surface size changes, including once after initialization. Reconfigure projection matrices and viewports here.

      Parameters

      • device: the graphics device bound to this view

      • width: the new drawable width in pixels

      • height: the new drawable height in pixels

      Specified by:
      onResize in interface Renderer

    • onFrame

      public void onFrame(GraphicsDevice device)
      Description copied from interface: Renderer

      Invoked once per frame to render the scene. Issue draw calls against the supplied device.

      Parameters
      • device: the graphics device bound to this view
      Specified by:
      onFrame in interface Renderer

    • onDispose

      public void onDispose(GraphicsDevice device)
      Description copied from interface: Renderer

      Invoked when the GPU context is being torn down (for example when the view is removed from the UI). Release any resources that are not owned by the device. May be invoked with a null device when the context was lost.

      Parameters
      • device: the graphics device bound to this view, or null if the context was already lost
      Specified by:
      onDispose in interface Renderer