3D Graphics and Shaders

The com.codename1.gpu package provides a portable, hardware accelerated 3D graphics API focused on games but useful anywhere you need GPU rendered content. It runs from one code base on the JavaSE simulator (OpenGL via JOGL), Android (OpenGL ES 2), iOS and macOS (Metal), the native Windows port (Direct3D 11), and the JavaScript port (WebGL). The API integrates with the normal Codename One UI: a 3D scene lives inside a regular component that you add to a Form like any other.

The API is intentionally "hybrid": a low level command layer (buffers, textures, render state, draw calls) for full control, plus high level helpers (meshes, materials, a camera) for common cases. Crucially, you never write shader source. Instead you describe a Material (a lighting model plus color and texture) and the engine generates the matching platform shader behind the scenes: GLSL ES on OpenGL ES and WebGL, GLSL on the desktop simulator, Metal Shading Language on iOS and Mac, and HLSL on the native Windows (Direct3D) port. This "engine-managed shader" approach is what keeps the same application code rendering identically across a range of different GPUs.

The main types are:

The renderer below draws a Phong lit cube. Primitives.cube builds the geometry, a Material describes the surface, and a Camera supplies the view. Notice there is no shader code anywhere.

setContinuous(true) runs an animation loop. For a static scene leave it off and call view.requestRender() whenever something changes; this conserves battery.

A Material is a declarative description of a surface. Its Type selects the lighting model:

A material also carries a base color (setColor, packed 0xAARRGGBB), an optional Texture (setTexture), and a RenderState controlling depth testing, alpha blending and face culling. Textures come from a Codename One Image or raw ARGB pixels:

Primitives builds common shapes (cube, quad). For custom geometry, allocate a VertexBuffer with a VertexFormat, fill the interleaved float data, and (optionally) an IndexBuffer:

Vertex buffers are allocated through the platform SIMD allocator, which on iOS (ParparVM) places the data at a fixed, aligned native address so it can be handed to Metal with no intermediate copy. You don’t need to do anything special to get this; just write into getData() and call setDirty() when you mutate it.

Real scenes use authored geometry. GltfLoader loads a glTF 2.0 model, both the binary .glb container and the JSON .gltf form with embedded buffers. loadModel returns the mesh together with the base-color texture from the model’s own material, so a textured model renders with no extra setup:

The model below is the Khronos "BoomBox" glTF sample (a CC0 model carrying its own base-color texture), loaded this way and drawn Phong lit:

Drive a value (a rotation angle, a position) over time and redraw. A continuous RenderView calls onFrame every frame; an on-demand view redraws when you call requestRender(). The grid below captures six fixed rotation stages of a spinning cube, each drawn into its own viewport in a single frame:

Skinned characters are deformed on the GPU. A mesh in VertexFormat.SKINNED carries up to four joint indices and weights per vertex, and Material.setSkinning(rows, count) hands the shader the first three rows of each joint matrix (up to Material.MAX_JOINTS). The vertex stage blends the joints, and the shadow pass does the same, so shadows bend with the mesh. AnimatedModel uses this path by itself whenever GraphicsDevice.isGpuSkinning() is true. On a device without GPU skinning, or for a skin with more joints than the limit, it falls back to skinning on the CPU.

Camera builds the view and projection matrices from an eye position, a look-at target and lens settings (setPerspective or setOrthographic). All matrix helpers live in Matrix4 (column-major float[16]): translation, scaling, rotation, multiply, lookAt, perspective, ortho. Pass a model matrix as the third argument to draw, or null for the identity.

Three settings turn a correctly lit scene into one that looks shot outdoors through a lens. All three start off, so a scene that never touches them renders exactly as before.

An Environment (GraphicsDevice.setEnvironment, or getEnvironment() on a GameView) holds the atmosphere every draw is shaded in:

Light.setShadows(true) renders the scene from the light into a shadow map before each frame, and lit materials are darkened where it’s blocked. Keep setShadowMap’s extent as small as the view allows and move `setShadowCenter with the camera, since the map’s resolution is spread over the area it covers. A material that shouldn’t cast (grass, particles) says so with setCastShadows(false).

A PostProcess on the view renders the scene offscreen and adds bloom, a color grade, a vignette and film grain on the way to the screen. Touch controls are drawn after it and are never graded.

PostProcess.addPass adds a full screen effect of your own, written with the same shader nodes as a material. The pass’s BASE_COLOR graph runs once per pixel: ShaderNode.screenUv() is the pixel’s place on screen and ShaderNode.sceneColor(uv) reads the frame. Passes run in order before the built-in effects. A frame with passes leaves out ambient occlusion, depth of field and the outline, because those read the scene’s depth.

Match the horizon color to the fog color and the far edge of the world disappears into the sky. A device that can’t render shadows or offscreen says so through GpuCapabilities.isShadowsSupported() and isPostProcessSupported(), and the scene is then drawn directly. The JavaSE software rasterizer applies the fog, the ambient, tone mapping and the sky gradient, but not shadows, clouds or the post chain.

A material’s look can be extended per pixel and per vertex without writing shader source. com.codename1.gpu.shader.ShaderNode is a typed expression in Java — arithmetic, mix, smoothstep, noise, texture reads and built in inputs such as worldPos(), uv(), time() and sunDir() — and every port prints the same graph as GLSL, Metal, or HLSL. A ShaderMaterial plugs graphs into hooks of the standard lighting path: VERTEX_OFFSET, BASE_COLOR, NORMAL, METALLIC, ROUGHNESS, EMISSIVE and DISCARD. A hook left unset keeps the material’s own behavior, so fog, shadows, the environment and tone mapping keep working around custom code. A material takes up to 16 uniforms and 4 textures, set by name with setUniform and setTexture.

Most scenes need no graph at all. com.codename1.gpu.shaders is a library of ready materials, each built only from public ShaderNode calls, so its source doubles as a set of examples:

ScenePresets bundles a light, an environment, a post chain and a sky that belong together: harbourDusk(), clearNoon(), overcast(), night(), desert() and arctic().

The post chain also offers FXAA, chromatic aberration and god rays from the sun’s position (setFxaa, setChromaticAberration, setGodRays).

Three more effects read the depth of the frame. setAmbientOcclusion darkens creases and the places where objects meet the ground, setDepthOfField keeps one distance sharp and blurs what’s nearer or farther, and setOutline inks every silhouette for a toon look. setColorLut then maps the graded color through a lookup strip, the way a film look is applied in a grading tool; ColorLuts builds strips (identity, filmic, posterize) to upload with GraphicsDevice.createTexture(ColorLuts.WIDTH, ColorLuts.HEIGHT, pixels). On an OpenGL ES 2 device without depth textures the three depth effects are skipped and the rest of the chain still runs.

A scene can also be drawn into a texture and shown on a surface of another scene — a security monitor, a mirror, a minimap. createRenderTarget(w, h) returns the texture (or null where the device can’t render offscreen), and draws between beginRenderTarget(target, clearColor) and endRenderTarget() land in it, with a depth buffer of its own. Use it as any material texture afterward and release it with dispose.

Animated shaders read time(). A GameView advances it every frame; a plain RenderView calls GraphicsDevice.setTime itself, and a test pins it to capture the same frame each run.

Many copies of one mesh — crates, rocks, a fleet — draw with GraphicsDevice.drawInstanced(mesh, material, matrices, colors, count), or Model.setInstances in a GameView. Each copy gets its own transform and tint, and a shader tells them apart through instanceId(), instanceRandom() and instanceColor().

The software rasterizer of the JavaSE simulator evaluates the vertex offset, color, emissive and discard hooks on the CPU, so a custom material keeps most of its look there; normal, metallic and roughness hooks need a GPU.

Querying capabilities at runtime:

Renderer callbacks run on the platform render thread, not the Codename One EDT. Don’t touch UI components from inside them. To move data the other way (for example to update a HUD label from a game loop), use CN.callSerially(…​).