just_graphics_engine 0.1.0
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
Render3DViewno longer clashes with Flutter'sRenderView):Old New RenderSceneRender3DSceneRenderViewRender3DViewRenderStatsRender3DStatsRenderViewModeRender3DViewModeLightTypeLight3DKind(the one enum for a 3-D light's kind; just_game_engine'sLight3DComponentuses it too)LightDataLight3DDataLightData.type,PunctualLight.typeLight3DData.kind,Punctual3DLight.kindDirectionalLightDirectional3DLightPunctualLightPunctual3DLightMaterialDataMaterial3DDataMaterialOverrideMaterial3DOverrideShapeMeshShape3DMeshShapeUvShape3DUvfitSunShadow(view, …)ShadowFitter().fit(view, …)(its scratch is the fitter's own)Saved data is unchanged:
.import.jsonand 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.texelandSkinPalette.frameare gone. -
Internal now (
@internal, exported by no library):RendererPipelines(nowRenderer3DPipelines),litLayout,litSkinnedLayout,halve(nowhalveImage), andFlutterGpuDevice(createGpuDevicemakes it).FrameArenas,loadShaderBundle, the glTF reader (AccessorReader,parseGlb,gltfToModel,decodeDataUri,externalUris, …) were reachable only throughsrc/imports and are marked internal. -
GpuCommandshasabandon(): aGpuDeviceof your own implements it. -
Cooked models are format 2, and only format 2 is read.
CookedModel.isCookedis false for a format-1 file (whose textures were stored premultiplied), so a loader falls back to the model file;CookedModel.readrefuses it;stampOfgives null. Every model is cooked again:cookStampnow coverscookerVersionand the files a model refers to (files:). -
EnvironmentMapData.build(andfromGradient,fromEquirect) makes levels down to 2×2, not 1×1: one level fewer, as many as Flutter GPU takes.NullGpuDevice.maxMipLevelsanswers as Flutter GPU does (no 1×1 level). -
The shader bundle no longer holds
UnlitVertex,UnlitFragmentandInstancedVertex, 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 barrelgpu/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.dartandradiance_hdr.dart,assets/model_import.dart→model_import_settings.dart,assets/shape_mesh.dart→shape_3d_mesh.dartandmesh_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.dartandlighting_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 importpackage:just_graphics_engine/fixtures.dartinstead ofsrc/testing/.
Added #
fixtures.dart:GlbWriter,skinnedBarGlb,jointChainGlbandmannequinGlbin pure Dart, for tools run withdart run(testing.dartexports them too).modelClipNamesOf(bytes): the names of a model's clips, asloadModelDatanames them (an animation's own name, oranimation <index>; none for an animation that moves no node), read from the JSON alone on the calling isolate; a.glbmay 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:)andcookerVersion.CookedModel.versionOf.Renderer3D.framesInFlight,maxFramesInFlight(2) andisBusy: skip a frame while the GPU is behind.Scene3DViewdoes.Renderer3D.render(…, frame:)andRenderTargetPool.endFrame(frame:): views drawn in one displayed frame share its number, so targets age by displayed frames.InstanceBatch.mirroredandInstanceBatch.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 inrendererNullShaders. - Dartdoc on every value of
GpuCompare,GpuCull,GpuTopology,GpuIndexType,GpuFilter,GpuAddress,GpuVertexFormatandLight3DKind; thepublic_member_api_docslint 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;Scene3DViewlives inrenderer/(still exported byjust_graphics_engine.dart, and now byrenderer.darttoo). Layers:assets,gpu,testing, thenrenderer.Renderer3Dis split: the class and the frame inrenderer_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 internalrenderer_3d_pipelines.dart.loadModelDatafetches each file a model refers to once, all at once, and reads a.gltf's JSON (and itsdata:URIs) in the background isolate.GpuModel.datakeeps 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
UniformWriterper uniform block, ranks lights without allocating, and fits shadows with aShadowFitter's own scratch;SkeletonandAnimationClipkeep 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
powper 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.
Scene3DViewpaints behind aRepaintBoundary.
Fixed #
- Textures were decoded premultiplied and blended as straight alpha: every texel that wasn't opaque drew darker than authored (glass, foliage fringes).
decodeImagenow keeps straight alpha. - A cooked model stayed "fresh" when a texture or buffer beside a
.gltfchanged, 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
.hdrtook 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 aFormatExceptionat load now. A sampler with no keys no longer writes another channel's value.decodeDataUrireads 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:
InstanceBatchinRenderScene.batches, each in a persistent instance buffer, culled whole and beyond its reach, casting shadows;RenderStats.batches. - Overlays and wireframes:
OverlayDrawinRenderScene.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.frameDatacame from Flutter GPU'sHostBuffer, 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:GpuDeviceover Flutter GPU (createGpuDevice, null with a reason where it can't run: the web, Impeller off, Android's OpenGL ES fallback), aNullGpuDevicethat records commands,PipelineSet,RenderTargetPool,SortKey,UniformWriterandClipFixup. 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):.glband.gltf, node hierarchies, every material map, sparse accessors,KHR_texture_transform,KHR_materials_unlit,KHR_materials_emissive_strength,KHR_mesh_quantizationandKHR_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 aShapeMesh;ShapeMesh.toPrimitiveandModelUploader.uploadPrimitiveput it on the GPU,ModelUploader.materialgives it a material made in code. renderer.dart:Renderer3Dwith 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.tryCreatemakes one on this platform's GPU, or gives null and says why.RenderStatscounts draws, shadow draws, casters, skinned instances and joints.Scene3DView: a widget that draws aRenderScenefrom aRenderViewevery 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
r32fshadow 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) andGpuEnvironmentMap. Lit surfaces take ambient light and reflections fromEnvironment.map;Environment.skyboxdraws 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) andcookModel, 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),GlbWriterfor generated fixtures, andskinnedBarGlb,jointChainGlbandmannequinGlb(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 aScene3DViewfrom an orbiting camera, with no game engine, and the Flutter GPU switch in every runner.- GPU tests (tag
gpu) run headless on Windows withflutter test --enable-impeller --enable-flutter-gpu --tags gpu.