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
    protected boolean
    beginPostEffects(PostProcess effects, int width, int height)
    The device's own post processing: redirects drawing into an offscreen image so endPostEffects can apply the built-in effects of effects.
    final 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
    beginRenderTarget(Texture target, int clearArgb)
    Sends the draws that follow into target until endRenderTarget, clearing its colour to clearArgb and its depth first.
    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.
    Texture
    createRenderTarget(int width, int height)
    Creates an offscreen image the scene can be drawn into with beginRenderTarget and then sampled like any other texture: a mirror, a security camera screen, a minimap, the refraction behind glass.
    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
    drawInstanced(Mesh mesh, Material material, float[] matrices, int[] colors, int count)
    Draws count copies of a mesh, each with its own transform and, optionally, colour: crates along a quay, a field of grass, a flock.
    protected void
    endPostEffects(float timeSeconds)
    Applies the effects passed to beginPostEffects and draws the result to the screen.
    final void
    endPostProcess(float timeSeconds)
    Applies the effects passed to beginPostProcess and draws the result to the screen.
    void
    endRenderTarget()
    Ends the pass beginRenderTarget started; drawing returns to the target and viewport that were active before it.
    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.
    float
    getTime()
    Returns the clock set with setTime.
    boolean
    isGpuSkinning()
    True if this device skins meshes on the GPU: it draws a mesh in VertexFormat.SKINNED with a material given Material.setSkinning by moving each vertex in its vertex stage.
    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.
    protected final void
    packDepthEffects(PostProcess effects, float[] out, int offset)
    Writes the parameters of the depth effects and the colour lookup into out from offset, twelve floats: ambient occlusion strength and radius in pixels, focus distance, depth of field blur in pixels, outline strength, the camera's near and far planes, lookup strength, and the outline colour as red, green, blue (0 to 1) and a zero.
    protected final void
    packPostEffects(PostProcess effects, float[] out, int offset)
    Writes the parameters of the post effects added after grain into out from offset: chromatic aberration, FXAA (0 or 1), god ray strength scaled by how visible the sun is, and the sun's position in texture space (0, 0 is the top left).
    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.
    void
    setTime(float seconds)
    Sets the clock that custom shaders read with com.codename1.gpu.shader.ShaderNode.time(), in seconds.
    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.

    • setTime

      public void setTime(float seconds)

      Sets the clock that custom shaders read with com.codename1.gpu.shader.ShaderNode.time(), in seconds. Call it once per frame before drawing; animated library shaders such as water move with it.

      Parameters
      • seconds: the time

    • getTime

      public float getTime()

      Returns the clock set with setTime.

      Returns

      seconds

    • 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.

    • createRenderTarget

      public Texture createRenderTarget(int width, int height)

      Creates an offscreen image the scene can be drawn into with beginRenderTarget and then sampled like any other texture: a mirror, a security camera screen, a minimap, the refraction behind glass.

      The result is an ordinary Texture; hand it to a material or to a ShaderMaterial texture slot, and release it with dispose(Texture). It has a depth buffer of its own while it is drawn into.

      The default implementation cannot draw offscreen and returns null, as the software simulator device does.

      Parameters

      • width: the width in pixels

      • height: the height in pixels

      Returns

      the target, or null when this device has no offscreen drawing

    • isGpuSkinning

      public boolean isGpuSkinning()

      True if this device skins meshes on the GPU: it draws a mesh in VertexFormat.SKINNED with a material given Material.setSkinning by moving each vertex in its vertex stage. Where it answers false, as the software simulator device does, skin on the CPU and draw the result as an ordinary mesh; com.codename1.gaming.AnimatedModel picks the path by itself.

      Returns

      false by default

    • beginRenderTarget

      public boolean beginRenderTarget(Texture target, int clearArgb)

      Sends the draws that follow into target until endRenderTarget, clearing its colour to clearArgb and its depth first. The viewport covers the whole target, and the camera, light and environment are the device's as usual, so set a camera for the view the target shows.

      Draw render targets first in a frame: before the shadow pass, before beginPostProcess and before the scene itself. They do not nest, and on some devices the depth of scene draws made earlier in the frame is not kept across one.

      Parameters

      • target: a texture from createRenderTarget on this device

      • clearArgb: the colour the target starts from

      Returns

      true if drawing now goes into the target

    • endRenderTarget

      public void endRenderTarget()
      Ends the pass beginRenderTarget started; drawing returns to the target and viewport that were active before it.

    • beginPostProcess

      public final 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. When effects has custom passes (PostProcess.addPass) and this device can draw into a render target, the scene goes into one, and endPostProcess runs the passes before the built-in effects.

      Draw the shadow pass and any render targets before this call.

      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; false means the caller draws straight to the screen

    • endPostProcess

      public final 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

    • beginPostEffects

      protected boolean beginPostEffects(PostProcess effects, int width, int height)

      The device's own post processing: redirects drawing into an offscreen image so endPostEffects can apply the built-in effects of effects. Custom passes are handled by beginPostProcess and never reach this.

      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

    • endPostEffects

      protected void endPostEffects(float timeSeconds)

      Applies the effects passed to beginPostEffects and draws the result to the screen.

      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

    • drawInstanced

      public void drawInstanced(Mesh mesh, Material material, float[] matrices, int[] colors, int count)

      Draws count copies of a mesh, each with its own transform and, optionally, colour: crates along a quay, a field of grass, a flock. The material's shader tells the copies apart with ShaderNode.instanceId, instanceRandom and instanceColor, so one material varies size, tint and motion across thousands of copies.

      Every device draws the copies one after another from a single compiled pipeline, changing only the transform and the per copy uniforms between them, which is what makes it cheaper than a model per copy: no state is looked up or rebound and the scene walks one node.

      Parameters

      • mesh: the mesh

      • material: the material shared by every copy

      • matrices: 16 column-major floats per copy

      • colors: an ARGB colour per copy, or null for white

      • count: how many copies to draw

    • 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.

    • packPostEffects

      protected final void packPostEffects(PostProcess effects, float[] out, int offset)

      Writes the parameters of the post effects added after grain into out from offset: chromatic aberration, FXAA (0 or 1), god ray strength scaled by how visible the sun is, and the sun's position in texture space (0, 0 is the top left). Every device packs them in this order, so the composite passes of every shading language agree.

      Parameters

      • effects: the post process being composited

      • out: the parameter array

      • offset: where to write the six floats

    • packDepthEffects

      protected final void packDepthEffects(PostProcess effects, float[] out, int offset)

      Writes the parameters of the depth effects and the colour lookup into out from offset, twelve floats: ambient occlusion strength and radius in pixels, focus distance, depth of field blur in pixels, outline strength, the camera's near and far planes, lookup strength, and the outline colour as red, green, blue (0 to 1) and a zero. Every device packs them in this order, so the composite passes of every shading language agree.

      Parameters

      • effects: the post process being composited

      • out: the parameter array

      • offset: where to write the twelve floats