The long awaited blending refactoring release 😉

We write release notes on the Github release page. But this release could use some extra explanation, I'll write it here for review, and will copy it to the release.

Introduction

This release represents a lot of work on refactoring how PyGfx deals with transparency. We recommend reading https://docs.pygfx.org/latest/transparency.html to learn how PyGfx works now.

The most important changes related to transparency:

The renderer.blend_mode is no more. Some modes like the 'ordered2' and 'weighted_plus' no longer exist. Instead, you can now set material.alpha_mode on each object separately. Yes, you can mix different modes in the same scene.

It does mean that as a user you'll have to be a bit more aware of whether your objects are transparent, and how to approach that. In short, the default material.alpha_mode='auto' works fine for opaque and most semi-transparent objects, as well as for objects that have mixed opaque/transparent fragments. But if you know your object is opaque, use alpha_mode='solid', and if it's transparent, use alpha_mode='blend'. For more context check https://docs.pygfx.org/latest/transparency.html#a-quick-guide-to-select-alpha-mode

We also changed some things on how we approach anti-aliasing:

• The SSAA (super-sample anti-aliasing) that we already applied now uses an improved filter (the Mitchell filter). The same improved filter is also used for upsampling. Also see the new renderer.pixel_scale and renderer.pixel_filter.
• We added support for PPAA (post-processing anti-aliasing) to improve the smoothness of the rendered result. It's enabled by default. See the new renderer.ppaa.
• The material.aa for text lines and points is now off by default, to prevent blending artifacts. Though we recommend turning it on for text for higher quality glyphs.
• See https://docs.pygfx.org/latest/aa.html for details.

API changes

Objects and materials:

• Removed WorldObject.render_mask.
• Added Material.alpha_mode, default is 'auto'.
• Adeded .alpha_config, .alpha_method (setting alpha_mode also sets these).
• Added Material.render_queue, default is None (auto).
• Added Material.depth_write, default is None (auto).
• Added `Material.depth_compare, default is "<".
• Added Material.alpha_test.
• Added Material.alpha_compare, default is "<".
• Removed material.color_is_transparent for Line, Mesh, Points, Text. Use material.color.a < 1 instead.
• Removed material.edge_color_is_transparent for Points. Use material.edge_color.a < 1 instead.
• Removed material.outline_color_is_transparent for Text. Use material.outline_color.a < 1 instead.

Renderer:

• Removed Renderer.blend_mode.
• The renderer.sort_objects is True by default.
• The renderer's sorting logic is completely overhauled.
• Added renderer.effect_passes.
• Added renderer.ppaa.
• Added renderer.pixel_scale.
• The renderer.pixel_filter is now a string instead of an int.
• Added renderer.clear() to clear render targets.

Commits

Changes related to transparency and anti-aliasing:

• Simplify blending by @almarklein in Simplify blending #1002
• Add support for post-processing effects by @almarklein in Add support for post-processing effects #1114
• Improve the interpolation filter in flush by @almarklein in Improve the interpolation filter in flush #1121
• Fix that snapshot may not include the last effect by @almarklein in Fix that snapshot may not include the last effect #1126
• Syncing ssaa.wgsl by @almarklein in Syncing ssaa.wgsl #1131
• Improve dithered alpha_mode by @almarklein in Improve dithered alpha_mode #1139
• Add support for FXAA and DDAA by @almarklein in Add support for FXAA and DDAA #1117
• remove unused variable in image_stitching example by @hmaarrfk in remove unused variable in image_stitching example #1143
• Add docs for blending by @almarklein in Add docs for blending #1124
• Implement material.alpha_mode to replace .blending and .transparent by @almarklein in Implement material.alpha_mode to replace .blending and .transparent #1144
• Allow calling renderer.clear(depth=True, color=True) by @hmaarrfk in Allow calling renderer.clear(depth=True, color=True) #1170
• Rename alpha-method 'composite' to 'blended' by @almarklein in Rename alpha-method 'composite' to 'blended' #1172
• Add renderer.pixel_scale by @almarklein in Add renderer.pixel_scale #1174
• Turn off material.aa by default by @almarklein in Turn off material.aa by default #1171
• Enable weighted blending between calls to render by @hmaarrfk in Enable weighted blending between calls to render #1148
• Add docs on aa by @almarklein in Add docs on aa #1173
• Make background use alpha_mode and render_queue correctly by @almarklein in Make background use alpha_mode and render_queue correctly #1180
• Add material.alpha_method (readonly) by @almarklein in Add material.alpha_method (readonly) #1184
• Refactor logic related to 'auto' mode by @almarklein in Refactor logic related to 'auto' mode #1186
• Tweak docs by @almarklein in Tweak docs #1188
• Add arg to Ruler for alpha_mode of child objects by @almarklein in Add arg to Ruler for alpha_mode of child objects #1189
• Remove that material.opacity affects alpha logic by @almarklein in Remove that material.opacity affects alpha logic #1190
• Small tweak to docs of render_queue by @almarklein in Small tweak to docs of render_queue #1194

Changes to the engine:

• Add support for custom orbit center in OrbitController by @panxinmiao in Add support for custom orbit center in OrbitController #1115
• Cloth Simulation with Compute Shaders by @panxinmiao in Cloth Simulation with Compute Shaders #1116
• Fix that the ruler did not take world transform into account by @almarklein in Fix that the ruler did not take world transform into account #1130
• update roll by @sawbz in update roll #1134
• Fix pan in orbit controller by @almarklein in Fix pan in orbit controller #1135
• fix GLTFMaterialsSheenExtension by @panxinmiao in fix GLTFMaterialsSheenExtension #1150
• Fixed some edge cases in the Interpolant by @panxinmiao in Fixed some edge cases in the Interpolant #1154
• Implement GpuCache with LRU strategy (split from Physically based transparency #974) by @panxinmiao in Implement GpuCache with LRU strategy (split from #974) #1142
• Add EXT_texture_webp support by @panxinmiao in Add EXT_texture_webp support #1155
• Support KHR_draco_mesh_compression by @panxinmiao in Support KHR_draco_mesh_compression #1159
• Fix keyframe optimization by @panxinmiao in Fix keyframe optimization #1166
• Fix docstring of get_bounding_box by @almarklein in Fix docstring of get_bounding_box #1178
• Make sure the pick face coords add up to one by @almarklein in Make sure the pick face coords add up to one #1179
• Support GLTF alphaMode by @almarklein in Support GLTF alphaMode #1177
• Dereference world-object in case its a weakproxy by @almarklein in Dereference world-object in case its a weakproxy #1183
• Can use wgpu 0.23 by @almarklein in Can use wgpu 0.23 #1193

Other changes:

• Use rendercanvas in all our examples by @almarklein in Use rendercanvas in all our examples #1127
• Minor tweaks to avoid warnings in CI by @almarklein in Minor tweaks to avoid warnings in CI #1129
• Fix vertical text because uharfbuzz 0.51 broke something by @hmaarrfk in Fix vertical text because uharfbuzz 0.51 broke something #1151
• Update uharfbuzz constraint for future proofing by @hmaarrfk in Update uharfbuzz constraint for future proofing #1152
• Adjust how version is reported when one checkouts a tag by @hmaarrfk in Adjust how version is reported when one checkouts a tag #1153
• Update validation example screenshot by @almarklein in Update validation example screenshot #1161
• updated "expected 1.0" to 1 year from today by @hmaarrfk in updated "expected 1.0" to 1 year from today #1160
• Add dedicated email address to coc by @almarklein in Add dedicated email address to coc #1181
• Update _version.py by @almarklein in Update _version.py #1185
• Add slotscheck to CI by @almarklein in Add slotscheck to CI #1187
• Switch to trusted publishing for PyPI publish in CI by @EpicWink in Switch to trusted publishing for PyPI publish in CI #1192