Skip to main content

just_graphics_engine 0.1.0 copy "just_graphics_engine: ^0.1.0" to clipboard
just_graphics_engine: ^0.1.0 copied to clipboard

3D renderer for Flutter on Flutter GPU: glTF 2.0 models, PBR materials, lights, shadows, skinned animation, image-based light and a scene widget.

0.1.0 #

The first release that isn't a dev release: from here its API follows semantic versioning (in 0.x, a breaking change moves the minor version). It is made for Flutter 3.47 — Flutter GPU is a preview, so each release targets one Flutter minor series (see the README's "Flutter versions"). Verified on Windows, Android (Vulkan) and the web; Linux, iOS and macOS are untested.

The package laid out by feature with one barrel per folder, its 3-D names tagged, Renderer3D split into parts, and a round of fixes: textures keep straight alpha, cooked models know when they are stale, alpha-masked casters cut their shadows out, mirrored models draw the right way out. Requires just_dart ^0.3.0.

Breaking #

  • Renamed, so 3-D names say so beside just_game_engine's 2-D ones (and Render3DView no longer clashes with Flutter's RenderView):

    Old New
    RenderScene Render3DScene
    RenderView Render3DView
    RenderStats Render3DStats
    RenderViewMode Render3DViewMode
    LightType Light3DKind (the one enum for a 3-D light's kind; just_game_engine's Light3DComponent uses it too)
    LightData Light3DData
    LightData.type, PunctualLight.type Light3DData.kind, Punctual3DLight.kind
    DirectionalLight Directional3DLight
    PunctualLight Punctual3DLight
    MaterialData Material3DData
    MaterialOverride Material3DOverride
    ShapeMesh Shape3DMesh
    ShapeUv Shape3DUv
    fitSunShadow(view, …) ShadowFitter().fit(view, …) (its scratch is the fitter's own)

    Saved data is unchanged: .import.json and the cooked header store values and keys, not type names, and a cooked light keeps its 'type' key.

  • Requires just_dart ^0.3.0, and re-exports its new names: Ray3 → Ray3D, JustMatrix4 → Matrix4Transforms (the extension's methods are unchanged).

  • Renderer bookkeeping left the objects drawn, for the renderer to keep (two renderers on two devices no longer share it): InstanceBatch.buffer, InstanceBatch.uploaded, GpuMaterial.uniforms, SkinPalette.texel and SkinPalette.frame are gone.

  • Internal now (@internal, exported by no library): RendererPipelines (now Renderer3DPipelines), litLayout, litSkinnedLayout, halve (now halveImage), and FlutterGpuDevice (createGpuDevice makes it). FrameArenas, loadShaderBundle, the glTF reader (AccessorReader, parseGlb, gltfToModel, decodeDataUri, externalUris, …) were reachable only through src/ imports and are marked internal.

  • GpuCommands has abandon(): a GpuDevice of your own implements it.

  • Cooked models are format 2, and only format 2 is read. CookedModel.isCooked is false for a format-1 file (whose textures were stored premultiplied), so a loader falls back to the model file; CookedModel.read refuses it; stampOf gives null. Every model is cooked again: cookStamp now covers cookerVersion and the files a model refers to (files:).

  • EnvironmentMapData.build (and fromGradient, fromEquirect) makes levels down to 2×2, not 1×1: one level fewer, as many as Flutter GPU takes. NullGpuDevice.maxMipLevels answers as Flutter GPU does (no 1×1 level).

  • The shader bundle no longer holds UnlitVertex, UnlitFragment and InstancedVertex, which only the package's tests used.

  • Files moved (for src/ imports, which nothing outside should make): gpu/device.dart → gpu/gpu_device.dart, gpu/caps.dart → gpu/gpu_caps.dart, gpu/formats.dart → gpu/gpu_formats.dart, gpu/create_device.dart → the barrel gpu/gpu.dart, gpu/backend_null/null_device.dart → gpu/backends/null_gpu_device.dart, gpu/backend_flutter_gpu/ → gpu/backends/; assets/environment_map.dart → environment_map_data.dart and radiance_hdr.dart, assets/model_import.dart → model_import_settings.dart, assets/shape_mesh.dart → shape_3d_mesh.dart and mesh_builder.dart, Pose → assets/pose.dart; renderer/renderer3d.dart → renderer_3d.dart (and its parts), renderer/render_scene.dart → render_3d_scene.dart, render_3d_view.dart and lighting_3d.dart, renderer/environment_map.dart → gpu_environment_map.dart, renderer/shadows.dart → sun_shadows.dart, ModelUploader → renderer/model_uploader.dart, OverlayDraw → overlay_draw.dart, widgets/scene_3d_view.dart → renderer/scene_3d_view.dart. Tools import package:just_graphics_engine/fixtures.dart instead of src/testing/.

Added #

  • fixtures.dart: GlbWriter, skinnedBarGlb, jointChainGlb and mannequinGlb in pure Dart, for tools run with dart run (testing.dart exports them too).
  • modelClipNamesOf(bytes): the names of a model's clips, as loadModelData names them (an animation's own name, or animation <index>; none for an animation that moves no node), read from the JSON alone on the calling isolate; a .glb may be cut after its JSON chunk. The loader and it share one rule, so a tool (the sprite editor's animator) lists the clips a game has.
  • modelFilesOf(bytes): the files a model refers to, as its fetch is asked for them. cookStamp(…, files:) and cookerVersion. CookedModel.versionOf.
  • Renderer3D.framesInFlight, maxFramesInFlight (2) and isBusy: skip a frame while the GPU is behind. Scene3DView does.
  • Renderer3D.render(…, frame:) and RenderTargetPool.endFrame(frame:): views drawn in one displayed frame share its number, so targets age by displayed frames.
  • InstanceBatch.mirrored and InstanceBatch.isMirrored. OverlayDraw(skin:): a skinned primitive's highlight follows its pose.
  • ModelUploader.decodeTextures: off where nothing is drawn (a null device standing in for a GPU), no image is decoded.
  • NullGpuDevice(record: false): no log, for a whole headless session.
  • GpuEnvironmentMap.maxLod; EnvironmentMapData.build(levels:); buildMips(maxSize:).
  • Material3DData.copyWith; ModelData.withoutImages.
  • Shaders: alpha-masked shadow casters (ShadowMaskedVertex, ShadowSkinnedMaskedVertex, ShadowSkinnedUniformMaskedVertex, ShadowMaskedFragment) and posed lines (WireSkinnedVertex, WireSkinnedUniformVertex), with their entries in rendererNullShaders.
  • Dartdoc on every value of GpuCompare, GpuCull, GpuTopology, GpuIndexType, GpuFilter, GpuAddress, GpuVertexFormat and Light3DKind; the public_member_api_docs lint keeps every public member documented.
  • test/library_layout_test.dart, adapted from just_game_engine's: every file exported or internal, one barrel per folder, only the gpu barrel exporting conditionally, no import loops, layers in order.

Changed #

  • lib/src/ is laid out by feature (gpu/, assets/, renderer/, testing/), each folder with one barrel the public libraries export; Scene3DView lives in renderer/ (still exported by just_graphics_engine.dart, and now by renderer.dart too). Layers: assets, gpu, testing, then renderer.
  • Renderer3D is split: the class and the frame in renderer_3d.dart, its passes in parts (draw_lists.dart, shadow_pass.dart, joint_palettes.dart, frame_uniforms.dart, post_process_3d.dart, editor_lines.dart), its pipelines in the internal renderer_3d_pipelines.dart.
  • loadModelData fetches each file a model refers to once, all at once, and reads a .gltf's JSON (and its data: URIs) in the background isolate.
  • GpuModel.data keeps no image's pixels once they are on the GPU; images are copied out of a GLB's buffer, and a cooked model's geometry and animations out of the file, so the file can be let go of.
  • The renderer reuses one UniformWriter per uniform block, ranks lights without allocating, and fits shadows with a ShadowFitter's own scratch; Skeleton and AnimationClip keep their scratch per object, not per process.
  • Cooking shrinks an oversized texture in the mip isolate, and averages sRGB levels through a table rather than a pow per channel; an environment map's half floats are converted with no allocation per value.
  • One shader-library cache, the device's (the loader keeps none); a failed load is tried again.
  • Scene3DView paints behind a RepaintBoundary.

Fixed #

  • Textures were decoded premultiplied and blended as straight alpha: every texel that wasn't opaque drew darker than authored (glass, foliage fringes). decodeImage now keeps straight alpha.
  • A cooked model stayed "fresh" when a texture or buffer beside a .gltf changed, or when the cooker did; the stamp was also not the same on the web.
  • Image-based light read levels spaced for one more level than Flutter GPU uploads: reflections were sharper than their roughness.
  • A mirrored instance (a negative scale) drew inside out: the front face now follows the transform's determinant, for instances and batches.
  • Alpha-masked casters and batches cast solid shadows: they are cut out in the shadow map now.
  • An equirectangular .hdr took one pixel per cube texel: a small sun usually vanished from reflections and ambient. The panorama is averaged first.
  • Transparent draws closer than 4 m apart (or past 1 km) drew in material order, not back to front.
  • A second UV set and joint influences past the fourth were dropped silently: the loader says so in ModelData.warnings.
  • A frame that threw while recording kept its arena and left its surface frame acquired (the next resize threw): it gives them back now.
  • Copies of a material (import settings, cooking) lost its UV mode and layers.
  • Malformed input threw RangeError (an accessor past its buffer view, a cut-short cooked file, an HDR run past its line or of length 0, which looped forever) or failed every frame (an animation sampler shorter than its keys): each is a FormatException at load now. A sampler with no keys no longer writes another channel's value. decodeDataUri reads percent-escaped bytes that aren't UTF-8.
  • A wireframe or overlay of a skinned mesh showed its bind pose at the model root.
  • Render targets of four or more views of different sizes were made again every frame.
  • Where 3-D is off (the web), every model texture was still decoded and mipped, and the null device's log grew for the session.

0.1.0-dev.2 #

  • Instance batches: InstanceBatch in RenderScene.batches, each in a persistent instance buffer, culled whole and beyond its reach, casting shadows; RenderStats.batches.
  • Overlays and wireframes: OverlayDraw in RenderScene.overlays, drawn last with line topology; GpuPrimitive.edges (ModelUploader.keepEdges).
  • View modes (RenderViewMode: lit, unlit, wireframe), a clip plane, and the editor's unlit view in the lit shader.
  • Layered materials (MaterialData.layered: four colour layers weighed by vertex colour) and texture coordinates in metres or from the world (MaterialData.uvMode); ModelUploader.material(maps:) takes every map.
  • Frames drawn before the GPU runs them keep their own data. GpuDevice.frameData came from Flutter GPU's HostBuffer, which hands a frame's memory out again four frames later whether or not the GPU has read it: an app drawing five or more views a frame (an editor's split view and its game preview) drew views with another's camera, sky and lights, flickering. Each frame now writes into memory of its own, reused once the GPU has finished with it, and so does each frame's joint texture.

0.1.0-dev.1 #

First release, a dev release: a 3D renderer for Flutter on Flutter GPU, standing alone (no game engine) and drawing the 3D of just_game_engine. Requires Flutter 3.47.1 or newer.

  • gpu.dart: GpuDevice over Flutter GPU (createGpuDevice, null with a reason where it can't run: the web, Impeller off, Android's OpenGL ES fallback), a NullGpuDevice that records commands, PipelineSet, RenderTargetPool, SortKey, UniformWriter and ClipFixup. The backend skips calls that repeat what a pass already holds, since draw calls cost tens of microseconds on Android.
  • assets.dart: glTF 2.0 loading (loadModelData): .glb and .gltf, node hierarchies, every material map, sparse accessors, KHR_texture_transform, KHR_materials_unlit, KHR_materials_emissive_strength, KHR_mesh_quantization and KHR_lights_punctual. Files that require Draco, meshopt or KTX2 are refused by name. Images decode once and get sRGB-correct CPU mips.
  • Meshes made in code: MeshBuilder (triangles, quads, faces, boxes, lathes, discs) builds a ShapeMesh; ShapeMesh.toPrimitive and ModelUploader.uploadPrimitive put it on the GPU, ModelUploader.material gives it a material made in code.
  • renderer.dart: Renderer3D with frustum culling, sorted and instanced draws, metallic-roughness PBR lit by a sun, 8 point/spot lights and a hemisphere ambient, a gradient sky, and HDR with 4x MSAA and ACES tonemapping. Renderer3D.tryCreate makes one on this platform's GPU, or gives null and says why. RenderStats counts draws, shadow draws, casters, skinned instances and joints.
  • Scene3DView: a widget that draws a RenderScene from a RenderView every frame (or when rebuilt), sizes the image from its layout, sets a perspective projection for its aspect ratio, and shows the reason when there is no GPU or drawing fails.
  • Sun shadows: two cascades of r32f shadow maps fitted to the view with texel snapping, 3×3 PCF and normal-offset bias (Renderer3D.shadows, ShadowSettings.cascades, cascadeSplit, fitSunShadow).
  • Image-based light: EnvironmentMapData (a gradient sky or an equirectangular Radiance .hdr, decodeRadianceHdr; GGX-prefiltered cube levels and SH9 diffuse light, built on another isolate) and GpuEnvironmentMap. Lit surfaces take ambient light and reflections from Environment.map; Environment.skybox draws it as the sky.
  • Fog, over the sky's horizon too; bloom (Renderer3D.bloom, BloomSettings) through a chain of half-size targets; FXAA (Renderer3D.fxaa) for when MSAA is too dear; DynamicResolution, which lowers a render scale while frames run long.
  • Skinned animation: skins and animations from glTF; AnimationClip (step, linear and cubic-spline keys), Pose (and blending), Skeleton, PosedModel; joint palettes in one float texture (instanced skinned draws) or, as a fallback, uniform blocks.
  • Model import: ModelImportSettings (saved beside a model as <model>.import.json: scale, largest texture, mipmaps, material changes) and cookModel, which writes a cooked copy (<model>.jmodel, CookedModel) with every texture decoded, shrunk and mipped: no glTF parsing, no image decoding where it is loaded. ETC2/ASTC compression is accepted in the settings but not made yet (cooked uncompressed, with a warning).
  • For editors and tools: GpuModel.withMaterialValues (previews change materials without uploading), ImageData.levels, ModelUploader.uploadImage.
  • testing.dart: GPU test helpers (gpuUnavailableReason, submitAndWait, readPixels, compareImages), GlbWriter for generated fixtures, and skinnedBarGlb, jointChainGlb and mannequinGlb (a walking character made in code).
  • Shaders compile into one bundle with the app's Flutter SDK (hook/build.dart, GLSL ES 3.00 on OpenGL ES). Web builds, JavaScript or WebAssembly, compile and leave the bundle out.
  • example/: models, walking characters, lights and a sky drawn by a Scene3DView from an orbiting camera, with no game engine, and the Flutter GPU switch in every runner.
  • GPU tests (tag gpu) run headless on Windows with flutter test --enable-impeller --enable-flutter-gpu --tags gpu.
0
likes
160
points
505
downloads

Documentation

API reference

Publisher

verified publisherjustunknown.com

Weekly Downloads

3D renderer for Flutter on Flutter GPU: glTF 2.0 models, PBR materials, lights, shadows, skinned animation, image-based light and a scene widget.

Repository (GitHub)
View/report issues
Contributing

Topics

#graphics #gltf #game-engine #gamedev #flutter-gpu

License

BSD-3-Clause (license)

Dependencies

flutter, flutter_gpu, flutter_gpu_shaders, hooks, just_dart, meta, vector_math

More

Packages that depend on just_graphics_engine