Class GraphicsDevice

java.lang.Object
com.codename1.gpu.GraphicsDevice
public abstract class GraphicsDevice extends Object

The low level command surface of the 3D API, bound to a single RenderView and its GPU context. A concrete subclass is provided by each platform backend (OpenGL ES on Android, WebGL on the browser, Metal on iOS, desktop GL on the simulator). Applications obtain the device from the Renderer callbacks and never construct it directly.

The device owns shader generation and caching: when draw is called it looks at the Material and the mesh VertexFormat, generates (once) the matching platform shader, uploads any dirty buffers and issues the draw call.

  • Constructor Summary

    Constructors
    Constructor
    Description
    GraphicsDevice()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    beginPostProcess(PostProcess effects, int width, int height)
    Redirects drawing into an offscreen image so endPostProcess can apply effects to it on its way to the screen.
    boolean
    beginShadowPass(Light light)
    Starts rendering the light's shadow map.
    abstract void
    clear(int argbColor, boolean color, boolean depth)
    Clears the framebuffer.
    IndexBuffer
    createIndexBuffer(int indexCount)
    Allocates an index buffer.
    abstract Texture
    createTexture(int width, int height, int[] argb)
    Creates a GPU texture from raw ARGB pixel data.
    abstract Texture
    createTexture(Image image)
    Creates a GPU texture from a Codename One image.
    VertexBuffer
    createVertexBuffer(VertexFormat format, int vertexCount)
    Allocates a vertex buffer.
    abstract void
    dispose(IndexBuffer buffer)
    Releases the GPU resources backing an index buffer.
    abstract void
    dispose(Texture texture)
    Releases the GPU resources backing a texture.
    abstract void
    dispose(VertexBuffer buffer)
    Releases the GPU resources backing a vertex buffer.
    abstract void
    draw(Mesh mesh, Material material, float[] modelMatrix)
    Draws a mesh with the supplied material and model matrix.
    void
    endPostProcess(float timeSeconds)
    Applies the effects passed to beginPostProcess and draws the result to the screen.
    void
    endShadowPass()
    Ends the shadow pass started by beginShadowPass, and restores the viewport and target that were active before it.
    Camera
    getCamera()
    Returns the active camera, or null if none was set.
    abstract GpuCapabilities
    getCapabilities()
    Returns the capabilities and limits of the underlying GPU.
    Environment
    getEnvironment()
    Returns the active environment.
    Light
    getLight()
    Returns the active light.
    protected final boolean
    isShadowMapCurrent()
    For a backend: true once a shadow pass has ended since the camera was last set, so the map belongs to this frame.
    void
    setCamera(Camera camera)
    Sets the active camera supplying the view and projection matrices used by subsequent draws.
    void
    setEnvironment(Environment environment)
    Sets the environment (fog, hemisphere ambient, tone mapping) used by subsequent draws.
    void
    setLight(Light light)
    Sets the active directional light used by lit materials.
    abstract void
    setViewport(int x, int y, int width, int height)
    Sets the viewport rectangle in pixels.
    protected final void
    shadowMapRendered()
    For a backend: records that a shadow pass of this frame has ended.

    Methods inherited from class Object

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

  • Constructor Details

    • GraphicsDevice

      public GraphicsDevice()

  • Method Details

    • getCapabilities

      public abstract GpuCapabilities getCapabilities()
      Returns the capabilities and limits of the underlying GPU.

    • createVertexBuffer

      public VertexBuffer createVertexBuffer(VertexFormat format, int vertexCount)

      Allocates a vertex buffer. The backing array is SIMD aligned so it can be uploaded to the GPU without an intermediate copy on ParparVM.

      Parameters

      • format: the interleaved vertex layout

      • vertexCount: the number of vertices

      Returns

      a new vertex buffer tracked by this device

    • createIndexBuffer

      public IndexBuffer createIndexBuffer(int indexCount)

      Allocates an index buffer.

      Parameters
      • indexCount: the number of indices
      Returns

      a new index buffer tracked by this device

    • createTexture

      public abstract Texture createTexture(Image image)

      Creates a GPU texture from a Codename One image.

      Parameters
      • image: the source image
      Returns

      a new texture

    • createTexture

      public abstract Texture createTexture(int width, int height, int[] argb)

      Creates a GPU texture from raw ARGB pixel data.

      Parameters

      • width: the texture width in pixels

      • height: the texture height in pixels

      • argb: width * height packed ARGB pixels in row major order

      Returns

      a new texture

    • clear

      public abstract void clear(int argbColor, boolean color, boolean depth)

      Clears the framebuffer.

      Parameters

      • argbColor: the packed ARGB clear color

      • color: true to clear the color buffer

      • depth: true to clear the depth buffer

    • setViewport

      public abstract void setViewport(int x, int y, int width, int height)
      Sets the viewport rectangle in pixels.

    • setCamera

      public void setCamera(Camera camera)

      Sets the active camera supplying the view and projection matrices used by subsequent draws.

      Setting the camera starts a new frame as far as shadows go: a shadow map rendered before it is not used again, so set the camera first and then run beginShadowPass.

      Parameters
      • camera: the camera

    • isShadowMapCurrent

      protected final boolean isShadowMapCurrent()
      For a backend: true once a shadow pass has ended since the camera was last set, so the map belongs to this frame. A frame that skipped the pass must not sample the one before it.

    • shadowMapRendered

      protected final void shadowMapRendered()
      For a backend: records that a shadow pass of this frame has ended.

    • getCamera

      public Camera getCamera()
      Returns the active camera, or null if none was set.

    • setLight

      public void setLight(Light light)

      Sets the active directional light used by lit materials.

      Parameters
      • light: the light

    • getLight

      public Light getLight()
      Returns the active light.

    • setEnvironment

      public void setEnvironment(Environment environment)

      Sets the environment (fog, hemisphere ambient, tone mapping) used by subsequent draws.

      Parameters
      • environment: the environment; null restores the default, which changes nothing

    • getEnvironment

      public Environment getEnvironment()
      Returns the active environment.

    • beginShadowPass

      public boolean beginShadowPass(Light light)

      Starts rendering the light's shadow map. Until endShadowPass, draw writes only depth as seen from the light, and skips materials that do not cast shadows. Draws after endShadowPass that receive shadows sample the map.

      The default implementation supports no shadows and returns false; the caller then skips the pass and draws as usual.

      Render the shadow pass before beginPostProcess, never inside it: both passes return to the target that was active when they began, so a shadow pass started offscreen would hand the post process its own image to draw into.

      Parameters
      • light: the light whose shadows to render; it must have shadows on
      Returns

      true if the pass started and the shadow casters should be drawn now

    • endShadowPass

      public void endShadowPass()
      Ends the shadow pass started by beginShadowPass, and restores the viewport and target that were active before it.

    • beginPostProcess

      public boolean beginPostProcess(PostProcess effects, int width, int height)

      Redirects drawing into an offscreen image so endPostProcess can apply effects to it on its way to the screen.

      The default implementation supports no post processing and returns false; the caller then draws straight to the screen.

      Parameters

      • effects: the effects to apply

      • width: the width of the frame in pixels

      • height: the height of the frame in pixels

      Returns

      true if drawing now goes offscreen

    • endPostProcess

      public void endPostProcess(float timeSeconds)

      Applies the effects passed to beginPostProcess and draws the result to the screen. Drawing goes to the screen again afterwards.

      Parameters
      • timeSeconds: a running clock, which animates the film grain

    • draw

      public abstract void draw(Mesh mesh, Material material, float[] modelMatrix)

      Draws a mesh with the supplied material and model matrix. The device composes camera.getViewProjection() * modelMatrix, binds the generated shader for the material, applies the material render state and issues the draw call.

      Parameters

      • mesh: the geometry to draw

      • material: how to shade the geometry

      • modelMatrix: the 16 element column-major model transform, or null for the identity

    • dispose

      public abstract void dispose(VertexBuffer buffer)
      Releases the GPU resources backing a vertex buffer.

    • dispose

      public abstract void dispose(IndexBuffer buffer)
      Releases the GPU resources backing an index buffer.

    • dispose

      public abstract void dispose(Texture texture)
      Releases the GPU resources backing a texture.