Add guides on how to manually collect bug report system information #58
@ -17,3 +17,12 @@ insert_final_newline = true
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
max_line_length = 120
|
||||
|
||||
# Makefile. Same as Blender.
|
||||
[{Makefile,GNUmakefile}]
|
||||
charset = utf-8
|
||||
trim_trailing_whitespace = true
|
||||
insert_final_newline = true
|
||||
indent_style = tab
|
||||
indent_size = 4
|
||||
max_line_length = 120
|
||||
|
||||
36
Makefile
Normal file
36
Makefile
Normal file
@ -0,0 +1,36 @@
|
||||
# SPDX-FileCopyrightText: 2024 Blender Authors
|
||||
#
|
||||
# SPDX-License-Identifier: GPL-2.0-or-later
|
||||
|
||||
define HELP_TEXT
|
||||
Convenience Targets
|
||||
Provided for building.
|
||||
|
||||
* html: Build HTML documentation (default).
|
||||
* clean: Clean the build.
|
||||
|
||||
endef
|
||||
# HELP_TEXT (end)
|
||||
|
||||
# Needed to ensure actions use this directory (especially removing files).
|
||||
BASE_DIR := ${CURDIR}
|
||||
|
||||
.DEFAULT_GOAL := html
|
||||
|
||||
html: .FORCE
|
||||
@cd $(BASE_DIR) && mkdocs build
|
||||
|
||||
@echo
|
||||
@echo "Docs built: ./site/index.html"
|
||||
|
||||
clean: .FORCE
|
||||
rm -rf $(BASE_DIR)/site
|
||||
|
||||
@echo
|
||||
@echo "Docs cleaned from ./site/*"
|
||||
|
||||
export HELP_TEXT
|
||||
help: .FORCE
|
||||
@echo "$$HELP_TEXT"
|
||||
|
||||
.FORCE:
|
||||
@ -14,42 +14,83 @@ writing this intro, this documentation is not complete, but merely a start.
|
||||
|
||||
Relevant links:
|
||||
|
||||
- [Project Baklava phase 1: multi-data-block animation][phase1] (projects.blender.org)
|
||||
- [2024: Animation 2025: Progress & Planning][blogpost-baklava] (code.blender.org)
|
||||
- [2023: Layered Animation workshop][workshop-2023] (code.blender.org)
|
||||
- [2022: Character Animation workshop](../../module/character_animation_workshop_2022.md)
|
||||
- [2022: Character Animation workshop][workshop-2022] (code.blender.org)
|
||||
- [Layered Animation: Open Questions](https://hackmd.io/@anim-rigging/SkNZ9pLKp) (on HackMD)
|
||||
|
||||
[phase1]: https://projects.blender.org/blender/blender/issues/120406
|
||||
[blogpost-baklava]: https://code.blender.org/2024/02/animation-2025-progress-planning/
|
||||
[workshop-2023]: https://code.blender.org/2023/07/animation-workshop-june-2023/
|
||||
[workshop-2022]: https://code.blender.org/2022/11/the-future-of-character-animation-rigging/
|
||||
|
||||
## Main Goals
|
||||
|
||||
In short, Baklava introduces a new ID data-block `Animation`, which will replace
|
||||
the `Action` as the defacto container of animation data.
|
||||
In short, Baklava brings new features to the `Action` data-block:
|
||||
|
||||
- Multiple data-blocks can be animated by a single `Animation` (and still have different animation).
|
||||
- Animation can be stored as layers.
|
||||
- Multiple data-blocks can be animated by a single `Action` (and still have different animation).
|
||||
- Animation can be stored in layers on an `Action` (rather than having separate NLA data-structures per animated data-block).
|
||||
|
||||
## Design
|
||||
|
||||
For the broad design, see the [2023 workshop][workshop-2023] blog post. Since
|
||||
then some things were changed / detailed, which are described here.
|
||||
|
||||
### No More Strips
|
||||
### Phase 1: Multi-data-block animation
|
||||
|
||||
The initial version of Baklava will not have strips. Animation is stored
|
||||
directly on the layer. This makes the whole UI/UX design a lot simpler, as each
|
||||
layer will simply have a well-defined value for each property at each point in
|
||||
time.
|
||||
Phase 1 of project Baklava will focus on multi-data-block animation. This makes it possible to have
|
||||
both an object and its data animated by the same `Action`. Examples are camera transform (object)
|
||||
and lens parameters (object data).
|
||||
|
||||
Strips will likely be introduced later, in order to be able to replace the NLA.
|
||||
However, the initial version of Baklava will have the animation data stored
|
||||
directly on the layer. This simplification will help to release *a* version
|
||||
earlier, to get it in the hands of animators for feedback.
|
||||
The initial version of Baklava will not have layers or strips, at least not from the user/UI
|
||||
perspective. Under the hood animation data is still stored on a layer with a single strip. These are
|
||||
all implicitly created, though. This makes the whole UI/UX design a lot simpler, and allows us to
|
||||
focus on the multi-data-block animation part first.
|
||||
|
||||
For an up to date plan, see [Project Baklava phase 1: multi-data-block animation][phase1].
|
||||
|
||||
#### Dividing Actions with Slots
|
||||
|
||||
An Action is a container that holds the animation data for one or more data-blocks. Data-blocks in
|
||||
Blender represent various types of data such as objects, armatures, or materials, which can all be
|
||||
animated.
|
||||
|
||||
To differentiate the animations for each data-block within an Action, the concept of Slots is used.
|
||||
Each Slot within an Action corresponds to a specific data-block, allowing for organized and precise
|
||||
animation control. This division ensures that animations for different data-blocks do not interfere
|
||||
with each other and can be managed separately.
|
||||
|
||||
#### Linking Data-blocks to Actions and Slots
|
||||
|
||||
Data-blocks are linked to Actions to define their animations. Each data-block points to the Action
|
||||
that contains its animation data and specifies which Slot within that Action it uses. This setup
|
||||
allows for a flexible animation system where multiple data-blocks can share the same Action but
|
||||
still have distinct animations through their respective Slots.
|
||||
|
||||
#### Action Independence
|
||||
|
||||
It is important to note that an Action itself does not decide what it will animate. Instead, it is
|
||||
the data-blocks that reference an Action and choose the appropriate Slot to define their animation.
|
||||
|
||||
#### Sharing Slots Across Data-blocks
|
||||
|
||||
In some cases, multiple data-blocks can share the same Slot. When this occurs, the data-blocks will
|
||||
be animated identically, as they are referencing the same set of animation data within the Action.
|
||||
However, sharing the same Slot is considered a corner case and is not expected to be widely used. It
|
||||
can be useful in specific scenarios where identical animation across multiple data-blocks is
|
||||
desired.
|
||||
|
||||
|
||||
### Phase 2: Layered Animation
|
||||
|
||||
Phase 2 of project Baklava will bring layered animation to the `Action`. There will likely be other
|
||||
work done between the two phases, in order for Phase 1 to receive the necessary feedback and
|
||||
subsequent adjustments.
|
||||
|
||||
### Channel Groups & F-Curve Ordering
|
||||
|
||||
`Action`s are separated into 'action groups'. These are arbitrarily named
|
||||
Legacy `Action`s are separated into 'action groups'. These are arbitrarily named
|
||||
groupings of F-Curves. This has certain downsides:
|
||||
|
||||
- **Grouping:** Some tooling assumes that these are *not* arbitrarily named, and
|
||||
|
||||
@ -1,62 +0,0 @@
|
||||
# Character Animation workshop (2022)
|
||||
|
||||
The goal of this three-day workshop will be to come up with a design for
|
||||
a new character animation system in Blender. It'll be the kickoff of a
|
||||
3-year project *Animation 2025*.
|
||||
|
||||
## Presentation and Results
|
||||
|
||||
The presentation is available on YouTube: [The Future of Character
|
||||
Animation & Rigging: a Q&A feedback
|
||||
session](https://www.youtube.com/watch?v=msOjFC03JRY)
|
||||
|
||||
- [Design Principles](https://docs.google.com/document/d/1qjD1MhXAFnnySSzey9DW-vumhtNavUxqCbBM9P30FzQ/edit)
|
||||
- [What's stopping you from animating in Blender?](https://docs.google.com/document/d/11_7rUJ-UJXH9vEMHHbq4oRAOkm71hjR9INcrKNWpB9E/edit)
|
||||
- [Blank Slate - Character Animation in Blender](https://docs.google.com/document/d/1fvxezZJHHHsa7bcufdRFpWyrqjQuVHqxNTUc5Sg0VCI/edit)
|
||||
- [PDF of the Mural workboard used during the workshop](https://download.blender.org/institute/sybren/animation-rigging/2022-character-animation-workshop/2022-animation-workshop-mural-download.pdf)
|
||||
(12½ MB)
|
||||
|
||||
<figure>
|
||||
<img src="../../../images/2022-animation-workshop-big-blocks.webp"
|
||||
title="Bigger topics for planning|thumb|center" />
|
||||
<figcaption>Bigger topics for planning|thumb|center</figcaption>
|
||||
</figure>
|
||||
|
||||
## Dates & Locations
|
||||
|
||||
**Date:** 24-26 October 2022
|
||||
|
||||
**Location:** [Blender Institute](https://www.blender.org/about/institute/)
|
||||
|
||||
**Remote:** The main communication channel is [\#animation-module on Blender Chat](https://blender.chat/channel/animation-module). Video
|
||||
meeting will happen via [Google Meet on the usual meeting ID](https://meet.google.com/ora-nbxv-evf).
|
||||
|
||||
## Show & Tell
|
||||
|
||||
If you're joining the workshop, or even if you just want the
|
||||
workshop-peoples to see something you think is important (max 5 minute
|
||||
video), **please use [this sign-up
|
||||
sheet](https://docs.google.com/forms/d/e/1FAIpQLSey84FhfB6yx-bf_GMqIgiIwhy05W-ystMfb_LVLLMA-U_HuA/viewform)**.
|
||||
It'll help us streamline the process.
|
||||
|
||||
## Schedule
|
||||
|
||||
Every day, there will be three "sync moments" to make sure online/remote
|
||||
attendees are in sync with what's happening at Blender HQ, and vice
|
||||
versa.
|
||||
|
||||
All times are in local time, so CEST / Amsterdam time.
|
||||
|
||||
- 10:00 morning kickoff
|
||||
- 14:00 after lunch
|
||||
- 18:00 end of day
|
||||
|
||||
## Documents
|
||||
|
||||
- [Design Principles](https://docs.google.com/document/d/1qjD1MhXAFnnySSzey9DW-vumhtNavUxqCbBM9P30FzQ/edit)
|
||||
- [What's stopping you from animating in Blender?](https://docs.google.com/document/d/11_7rUJ-UJXH9vEMHHbq4oRAOkm71hjR9INcrKNWpB9E/edit)
|
||||
- [Blank Slate - Character Animation in Blender](https://docs.google.com/document/d/1fvxezZJHHHsa7bcufdRFpWyrqjQuVHqxNTUc5Sg0VCI/edit)
|
||||
- [Workshop schedule](https://docs.google.com/spreadsheets/d/1dBNl54Oz4X4S21z83jBFWlAOWTUQ8KPUAmZcxBhkBf4/edit)
|
||||
- [Sign-up Sheet](https://docs.google.com/forms/d/e/1FAIpQLSey84FhfB6yx-bf_GMqIgiIwhy05W-ystMfb_LVLLMA-U_HuA/viewform)
|
||||
([edit](https://docs.google.com/forms/d/1xVXAszg1wfFj4bcKYxIYkca5rc7pe88Mf7RpNSI_-r0/edit?usp=drive_web))
|
||||
- [Mural, which served as a work/brainstorm board during the workshop](https://app.mural.co/invitation/mural/home4643/1665674871684?sender=u6f41ad2ad961ab9f6e6a1021&key=91496bec-547f-44bc-a122-3ba0e5d32613)
|
||||
@ -22,4 +22,3 @@ Currently the module are working on [Project Baklava][baklava].
|
||||
|
||||
- [Bigger Projects](bigger_projects.md): broad ideas for the future.
|
||||
- [Weak Areas](weak_areas.md): areas of the Animation & Rigging system that could use improvement.
|
||||
- [Character Animation Workshop 2022](character_animation_workshop_2022.md)
|
||||
|
||||
@ -1,3 +1,2 @@
|
||||
- [Character Animation Workshop (2022)](character_animation_workshop_2022.md)
|
||||
- [Bigger Projects](bigger_projects.md)
|
||||
- [Weak Areas](weak_areas.md)
|
||||
|
||||
24
docs/features/asset_system/asset_editing.md
Normal file
24
docs/features/asset_system/asset_editing.md
Normal file
@ -0,0 +1,24 @@
|
||||
# Asset Editing
|
||||
|
||||
Under certain conditions, it is possible to edit assets that are not stored in the currently open
|
||||
file. This happens through special asset system managed files (as opposed to normal user managed
|
||||
files), and the `BKE_asset_edit.hh` API. Every such editable asset is saved in a single such file,
|
||||
together with its dependencies (and external files packed).
|
||||
|
||||
Only brush assets support this currently.
|
||||
|
||||
## Asset System Files (`.asset.blend` Files)
|
||||
|
||||
These files are indicated by a dedicated flag (`G_FILE_ASSET_EDIT_FILE`) stored in the file's
|
||||
"global" data section, and use the `.asset.blend` file extension. Both the flag and the extension
|
||||
need to be used for a file to be considered an asset system file. That means users may still use
|
||||
the `.asset.blend` extension for normal files. It's just a useful indicator for them, but also so
|
||||
Blender can tell if a file *may* be an asset file without having to open it it.
|
||||
|
||||
The design is to let the asset system regenerate these files when user's save changes to the
|
||||
assets. This way we keep the updating simple, and avoid many possible issues coming from loading
|
||||
and saving assets in normal, user managed .blend files. If users could open and overwrite these
|
||||
special .asset.blend files, user created data would be stored in them that would be lost the next
|
||||
time the asset system regenerates the files. That's why these files need to be special. Users can
|
||||
open, but not save these files (but use "Save As" to create a new, normal file). Warnings are
|
||||
displayed in the UI to notify the user about this.
|
||||
@ -88,30 +88,6 @@ Notes:
|
||||
the code can assume that no other part of Blender added an asset
|
||||
representation in question, it can safely remove it.
|
||||
|
||||
### Asset Identifier
|
||||
|
||||
Information to uniquely identify and locate an asset.
|
||||
|
||||
`AssetIdentifier` combines a custom asset library location with a
|
||||
custom relative asset identifier (identifier for the asset within the
|
||||
asset library), so that an asset can be uniquely identified and located.
|
||||
Currently the asset library location and the relative asset identifier
|
||||
need to add up to an absolute ID library path. For example the asset
|
||||
library root path could be `/home/assets/` and the relative asset path
|
||||
`subdir/asset.blend/Materials/Material.001`, adding up to
|
||||
`/home/assets/subdir/assets.blend/Materials/Material.001`.
|
||||
|
||||
> NOTE: **Asset identifier paths locate the asset, not the asset
|
||||
library**
|
||||
> Just from looking at the full path generated from an asset
|
||||
> identifier, it's not clear which asset library an asset representation
|
||||
> belongs to. In the example above, `/home/` and `/home/assets/` may both
|
||||
> be different asset libraries.
|
||||
|
||||
This is a runtime only identifier and should not be stored on disk in
|
||||
any way. Otherwise the identifier breaks when asset data is shared with
|
||||
another machine or user.
|
||||
|
||||
### ID Assets
|
||||
|
||||
Currently, all assets must use Blender ID data-blocks (Blender objects,
|
||||
|
||||
BIN
docs/features/asset_system/img/asset_shelf.png
(Stored with Git LFS)
BIN
docs/features/asset_system/img/asset_shelf.png
(Stored with Git LFS)
Binary file not shown.
@ -3,6 +3,7 @@
|
||||
- User Interface
|
||||
- [Asset Browser](user_interface/asset_browser.md)
|
||||
- user_interface/*.md
|
||||
- [Asset Editing](asset_editing.md)
|
||||
- [Asset Bundles](asset_bundles/)
|
||||
- [Brush Assets](brush_assets.md)
|
||||
- [FAQ](faq.md)
|
||||
|
||||
@ -1,55 +0,0 @@
|
||||
# EEVEE GPU Pipeline
|
||||
|
||||
This section describes how EEVEE uses the GPU to come to the final
|
||||
image. In this page we will use the [Tree
|
||||
Creature](https://download.blender.org/demo/eevee/tree_creature/tree_creature.blend)
|
||||
demo file from Daniel Bystedt. As it uses many areas of the render
|
||||
pipeline.
|
||||
|
||||
Note that EEVEE is continuously in development and you should be aware
|
||||
that this document does not reflect the latest changes. Use this
|
||||
information to get a head start at understanding how EEVEE works from a
|
||||
developers point of view.
|
||||
|
||||
## Update Light & Shadows
|
||||
|
||||
At the beginning of each sample EEVEE will make sure that the light
|
||||
probes, shadow maps and reflection planes are updated. When they need to
|
||||
be updated they will.
|
||||
|
||||
The first step is to update the shadow. During this step the textures
|
||||
that will contain the shadow maps are allocated and marked to be updated
|
||||
when a light source request to be updated.
|
||||
|
||||
- `eevee_shadows.c`#`EEVEE_shadows_update`
|
||||
- `eevee_lightprobes.c`#`EEVEE_lightprobes_refresh`
|
||||
- `eevee_lightprobes.c`#`EEVEE_lightprobes_refresh_planar`
|
||||
- `eevee_shadows.c`#`EEVEE_shadows_draw`
|
||||
|
||||
## Render the Depth Pass
|
||||
|
||||
The depth textures are updated. EEVEE has two depth texture (with and
|
||||
without culling)
|
||||
|
||||
Calculate a cubemap from the world.
|
||||
|
||||
## Update the light probes and reflection planes
|
||||
|
||||
## Draw Shadows
|
||||
|
||||
This step will update the shadow maps
|
||||
|
||||
## Bloom
|
||||
|
||||
Bloom is a screen space effect that happens after the samples have been
|
||||
merged. It consist out of several screen space kernels.
|
||||
|
||||
- Down-sample the color buffer doing a small blur during each step
|
||||
- Accumulate bloom color using previously down-samples color buffers and
|
||||
do an up-sample blur for each new accumulated layer
|
||||
- Finally add accumulation buffer onto the source color buffer.
|
||||
|
||||
### Important Files
|
||||
|
||||
- `eevee_bloom.c`
|
||||
- `effect_bloom_frag.glsl`
|
||||
3
docs/features/eevee/img/film_naming_convention.svg
Normal file
3
docs/features/eevee/img/film_naming_convention.svg
Normal file
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 13 KiB After Width: | Height: | Size: 13 KiB |
3
docs/features/eevee/img/film_resampling.svg
Normal file
3
docs/features/eevee/img/film_resampling.svg
Normal file
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 15 KiB After Width: | Height: | Size: 15 KiB |
3
docs/features/eevee/img/film_upsampling.svg
Normal file
3
docs/features/eevee/img/film_upsampling.svg
Normal file
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
@ -1,26 +1,27 @@
|
||||
# Eevee
|
||||
|
||||
Eevee is a draw/render engine that uses game engine like techniques to
|
||||
provide a fast render engine.
|
||||
Eevee is a draw/render engine that uses game engine like techniques to provide fast rendering and feedback.
|
||||
|
||||
## Design principles
|
||||
|
||||
Eevee should be a drop in replacement for Cycles. Eevee is used to draw the material preview mode for Cycles. Therefore the shading is tweaked to ensure that it follows Cycles as close as possible, but still be fast in rendering.
|
||||
Eevee is build to be a realtime alternative to Cycles with more flexibility in its rendering pipeline. Frame render time is the first focus to be able to deliver fast animation render. Eevee is also used to draw the material preview mode for Cycles. Therefore the shading is tweaked to ensure that it follows Cycles as close as possible, but still be fast to render.
|
||||
|
||||
## Classes
|
||||
- [Views](view.md)
|
||||
|
||||
## Modules
|
||||
|
||||
- [World](modules/world.md)
|
||||
- [Lookdev](modules/lookdev.md)
|
||||
- [Reflection Probes](modules/reflection_probes.md)
|
||||
- [Sphere Light-Probes](modules/lightprobe_sphere.md)
|
||||
- [Shadow](modules/shadow.md)
|
||||
- [Film](modules/film.md)
|
||||
- [Pipeline](modules/pipeline.md)
|
||||
|
||||
## Views
|
||||
|
||||
- [Capture](views/capture.md)
|
||||
## Pipelines
|
||||
|
||||
- [Background](pipelines/background.md)
|
||||
- [World](pipelines/world.md)
|
||||
- [DeferredProbePipeline](pipelines/probe.md)
|
||||
- [Deferred](pipelines/deferred.md)
|
||||
|
||||
## Shaders
|
||||
|
||||
|
||||
32
docs/features/eevee/modules/film.md
Normal file
32
docs/features/eevee/modules/film.md
Normal file
@ -0,0 +1,32 @@
|
||||
# Film Module
|
||||
|
||||
The film contains the final image buffers at output resolution after render region cropping.
|
||||
It stores all render passes results and the per pixel weight.
|
||||
|
||||
Here is a schematic of film extents and offsets looks like.
|
||||
|
||||
|
||||
|
||||
In the code, we have:
|
||||
- `display_extent` refering to either the render result extent.
|
||||
- `film_extent` refering to either the render region extent.
|
||||
- `render_extent` refering to either the render target extent.
|
||||
|
||||
## Jitter
|
||||
|
||||
For each render sample, we choose a random position inside the **render pixel area**. This random offset is applied to the projection matrix (`winmat` in the code) and render pixels colors are computed.
|
||||
|
||||
## Resampling
|
||||
|
||||
After rendering, the film samples the neighboring rendered pixels and weight them according to the pixel filter. The temporal re-projection and firefly filter is optionally done at this stage.
|
||||
The set of neighbor pixels to read and their weights are precomputed on CPU as they are all the same for all final pixels.
|
||||
|
||||
|
||||
|
||||
For data passes only the closest sample is kept and no weighted average is performed, avoiding value changes.
|
||||
|
||||
## Up-scaling
|
||||
|
||||
When using up-scaling (`Render Settings > Performance > Viewport > Pixel Size`), the render target is not at native resolution. The weights cannot be pre-computed and are recomputed per final pixel on the GPU.
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# Reflection probes
|
||||
# Sphere Light-Probes
|
||||
|
||||
To improve performance radiance light in the scene can be recorded in a reflection probe.
|
||||
There are two kind of reflection probes.
|
||||
To improve performance radiance light in the scene can be recorded in a sphere probe.
|
||||
There are two kind of sphere probes.
|
||||
|
||||
- World: Records the light from the background only.
|
||||
- Probe: Records light from geometry in the scene from a specific location.
|
||||
@ -10,11 +10,11 @@ There are two kind of reflection probes.
|
||||
flowchart LR
|
||||
RenderCubemap --> RemapCubeToOctahedralProjection --> UpdateWorldIrradianceFromOctahedralProjection
|
||||
```
|
||||
Each reflection probe is first rendered in a cubemap. See `CaptureView::render_world` or `CaptureView::render_probes`.
|
||||
The cubemap is remapped to octahedral projection. See `ReflectionProbeModule::remap_to_octahedral_projection`.
|
||||
Each sphere probe is first rendered in a cubemap. See `CaptureView::render_world` or `CaptureView::render_probes`.
|
||||
The cubemap is remapped to octahedral projection. See `SphereProbeModule::remap_to_octahedral_projection`.
|
||||
|
||||
In case we are creating a reflection probe for a world the irradiance of the world should also be updated.
|
||||
See `ReflectionProbeModule::update_world_irradiance`
|
||||
In case we are creating a sphere probe for a world the irradiance of the world should also be updated.
|
||||
See `SphereProbeModule::update_world_irradiance`
|
||||
|
||||
|
||||
## World probe baking
|
||||
@ -23,7 +23,7 @@ See `ReflectionProbeModule::update_world_irradiance`
|
||||
sequenceDiagram
|
||||
participant Instance as Instance
|
||||
participant View as CaptureView
|
||||
participant Module as ReflectionProbeModule
|
||||
participant Module as SphereProbeModule
|
||||
participant Pipeline as WorldProbePipeline
|
||||
|
||||
activate Instance
|
||||
@ -58,27 +58,27 @@ sequenceDiagram
|
||||
|
||||
## Reflection probe baking
|
||||
|
||||
When a change is detected for a reflection probe it is marked to be updated. Prerequisites to update
|
||||
the reflection probes are:
|
||||
When a change is detected for a sphere probe it is marked to be updated. Prerequisites to update
|
||||
the sphere probes are:
|
||||
|
||||
- All material shaders should have been compiled.
|
||||
- The `DeferredProbePipeline` should be activated. To save overhead the `DeferredProbePipeline` and
|
||||
the (`probe_prepass`, `probe_shading`) material passes are only created and populated when there are
|
||||
probes that needs to be updated.
|
||||
|
||||
The previous state of the reflection probes will be used, until the reflection probes are updated.
|
||||
The previous state of the sphere probes will be used, until the sphere probes are updated.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Instance as Instance
|
||||
participant View as CaptureView
|
||||
participant Module as ReflectionProbeModule
|
||||
participant Module as SphereProbeModule
|
||||
participant Pipeline as DeferredProbePipeline
|
||||
|
||||
activate Instance
|
||||
Instance->>View: render_probes()
|
||||
activate View
|
||||
loop while reflection probes left to update
|
||||
loop while sphere probes left to update
|
||||
View->>Module: update_info_pop
|
||||
activate Module
|
||||
deactivate Module
|
||||
@ -106,7 +106,7 @@ sequenceDiagram
|
||||
## Octahedral mapping
|
||||
|
||||
To reduce memory needs and improve sampling performance the cubemap
|
||||
is stored in octahedral mapping space. This is done in `eevee_reflection_probe_remap_comp.glsl`.
|
||||
is stored in octahedral mapping space. This is done in `eevee_lightprobe_sphere_remap_comp.glsl`.
|
||||
|
||||
The regular octahedral mapping has been extended to fix leakages at the edges of the texture
|
||||
and to be able to be used on an atlas texture and by sampling the texture once.
|
||||
@ -140,7 +140,7 @@ The octahedral map has an additional of 8 pixels of border on each side to suppo
|
||||
Diffuse lighting in the scene requires an `Irradiance Volume` object. When a scene
|
||||
doesn't have this object setup the world light would not be visible on diffuse objects.
|
||||
We update the first brick of the irradiance atlas texture with the world lighting so it will
|
||||
still be visible. This is done inside `ReflectionProbeModule::update_world_irradiance`.
|
||||
still be visible. This is done inside `SphereProbeModule::update_world_irradiance`.
|
||||
|
||||
`eevee_reflection_probe_update_irradiance_comp.glsl` calculates the spherical harmonics
|
||||
by evaluating the octahedral mapped world probe and stores the calculated spherical
|
||||
@ -162,7 +162,7 @@ a higher one and has enough data to capture the probe.
|
||||
|
||||
## Storage
|
||||
|
||||
The recorded reflection probes are stored in a single texture array. Each probe
|
||||
The recorded sphere probes are stored in a single texture array. Each probe
|
||||
can be of any resolution as long as it is a power of 2 and not larger than 2048 or smaller than 64.
|
||||
So valid options are (2048x2048, 1024x1024, 512x512, etc).
|
||||
|
||||
@ -191,7 +191,7 @@ resolutions on the same layer. Lets see an example how that works
|
||||
|
||||
### Example
|
||||
|
||||
Lets assume we have a world probe with the resolution of 1024x1024 and 2 reflection probes
|
||||
Lets assume we have a world probe with the resolution of 1024x1024 and 2 sphere probes
|
||||
with the resolution of 512x512. The resolution of the texture is 2048x2048. This could be
|
||||
stored in the texture as follow
|
||||
|
||||
@ -249,9 +249,9 @@ the first empty area.
|
||||
Evaluation is implemented in `eevee_reflection_probe_eval_lib.glsl`.
|
||||
|
||||
|
||||
1. Select the closest reflection probe. This is done by calculating the distance between P and the position of the reflection probe.
|
||||
2. Get the pixel based of the closest reflection probe for the needed vector
|
||||
3. If pixel is transparent or no reflection probe is available.
|
||||
1. Select the closest sphere probe. This is done by calculating the distance between P and the position of the sphere probe.
|
||||
2. Get the pixel based of the closest sphere probe for the needed vector
|
||||
3. If pixel is transparent or no sphere probe is available.
|
||||
* get the world background based on the same vector
|
||||
* mix the background with the pixel from the reflection probe.
|
||||
* mix the background with the pixel from the sphere probe.
|
||||
4. Apply GGX BRDF
|
||||
@ -61,7 +61,7 @@ classDiagram
|
||||
```
|
||||
|
||||
`LookdevModule::draw` updates the internal sphere textures. `LookdevModule::display` displays the last textures on the active framebuffer
|
||||
[LookdevView](../views/lookdev.md) is used to create an view from the orientation of the current viewport.
|
||||
[LookdevView](../view.md#lookdev-view) is used to create an view from the orientation of the current viewport.
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
|
||||
59
docs/features/eevee/modules/pipeline.md
Normal file
59
docs/features/eevee/modules/pipeline.md
Normal file
@ -0,0 +1,59 @@
|
||||
# Pipelines
|
||||
|
||||
A pipeline is a combination of one or multiple `draw::Pass` along with some internal logic for rendering. The pass types an object can subscribe to is listed by `eMaterialPipeline`. The objects subscribe to the `draw::Pass` with its associated shaders.
|
||||
|
||||
A single object can subscribe to multiple pipelines. A renderable object type is called a geometry type and listed in `eMaterialGeometry`.
|
||||
|
||||
Pipelines are filled with scene data and are view agnostic. Multiple views can call the same pipeline (e.g. the 6 views of a cubemap). View dependant resources should be stored inside [views](../view.md) and passed to the `render()` method of the pipelines (e.g. `ShadingView::rt_buffer_opaque_`).
|
||||
|
||||
## Material Pipeline
|
||||
|
||||
A core design principle of EEVEE is that all pipelines should be compatible with all geometry type (with a few exceptions).
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Mesh]
|
||||
B[Curves]
|
||||
D[Point Cloud]
|
||||
C[Volume]
|
||||
E[World]
|
||||
|
||||
classDef geometry stroke:#f66
|
||||
class A,B,C,D,E geometry;
|
||||
|
||||
I[Deferred]
|
||||
J[Forward]
|
||||
K[Shadow]
|
||||
L[Volume]
|
||||
M[Background]
|
||||
N[World]
|
||||
|
||||
classDef pipeline stroke:#66f
|
||||
class I,J,K,L,M,N pipeline;
|
||||
|
||||
E --> L & M & N
|
||||
C --> L
|
||||
A & B & D --> Reroute{Solid} --> I & J & K & L
|
||||
|
||||
S[Prepass]
|
||||
T[Gbuffer]
|
||||
U[Prepass]
|
||||
V[Shading]
|
||||
W[Occupancy]
|
||||
X[Material]
|
||||
Y[Shadow]
|
||||
Z[World]
|
||||
|
||||
classDef shader stroke:#6f6
|
||||
class S,T,U,V,W,X,Y,Z shader;
|
||||
|
||||
I --> S & T
|
||||
J --> U & V
|
||||
K --> Y
|
||||
L --> W & X
|
||||
M & N --> Z
|
||||
```
|
||||
Red is geometry type, blue is pipeline type, green is shader pass type.
|
||||
|
||||
Internally, the pass type maps to a fragment shader and the geometry type to a vertex shader. Some geometry type still need some special code in the fragment stage, and vice-versa, some pipelines need adjustments of the vertex shader. For this reasons, the `MAT_GEOM_*` (for geometry types) and `MAT_*` (for pipeline types) exists.
|
||||
|
||||
194
docs/features/eevee/modules/shadow.md
Normal file
194
docs/features/eevee/modules/shadow.md
Normal file
@ -0,0 +1,194 @@
|
||||
# Virtual Shadow Maps
|
||||
|
||||
EEVEE uses shadow mapping as its primary shadow solution. This is compatible with all pipelines (deferred, forward and volume), offers good performance and allows caching.
|
||||
|
||||
Sun lights use either a [clipmap](https://notkyon.moe/vt/Clipmap.pdf) (for high field of view) or a [cascade](https://learnopengl.com/Guest-Articles/2021/CSM) of shadow maps (for shallow field of view).
|
||||
|
||||
Local lights use local space shadow cubemaps. This allows to skip faces of the cube that are not used by certain light types (area lights, spot lights).
|
||||
|
||||
Each shadow map is stored as a [virtual textures](https://www.researchgate.net/publication/265202211_Accelerating_Virtual_Texturing_Using_CUDA). There is conceptually one virtual texture for each cubeface, clipmap level and cascade level. However, all of these virtual shadow maps have the same physical memory pool which is a single texture atlas (`eevee::ShadowModule::atlas_tx_`).
|
||||
|
||||
All the virtual texturing is custom implemented and does not rely on the driver own virtual texturing capabilities. The whole page allocation and update logic all runs on the GPU with no synchronization.
|
||||
|
||||
## Layout
|
||||
One virtual shadow map is composed of a descriptor `ShadowTileMapData` and a table of virtual page info `ShadowTileData`.
|
||||
|
||||
Here is how classes are referenced.
|
||||
```mermaid
|
||||
flowchart LR
|
||||
light["`***Light***`"]
|
||||
sun_shadow["`***ShadowDirectional***`"]
|
||||
local_shadow["`***ShadowPunctual***`"]
|
||||
sun_tilemap["`***ShadowTileMap***`"]
|
||||
sun_tilemap_data["`***ShadowTileMapData***`"]
|
||||
tile_pool["`***ShadowTileData***`"]
|
||||
altas["`Shadow Atlas`"]
|
||||
|
||||
subgraph CPU
|
||||
light --> |directional| sun_shadow
|
||||
light --> |punctual| local_shadow
|
||||
sun_shadow --> |tilemaps_| sun_tilemap
|
||||
local_shadow --> |tilemaps_| sun_tilemap
|
||||
end
|
||||
|
||||
sun_tilemap -.-> sun_tilemap_data
|
||||
|
||||
subgraph GPU
|
||||
sun_tilemap_data --> |tiles_index| tile_pool --> |page| altas
|
||||
end
|
||||
|
||||
classDef gpu_node_class stroke:#f66
|
||||
classDef cpu_node_class stroke:#66f
|
||||
|
||||
class light,sun_shadow,local_shadow,sun_tilemap cpu_node_class;
|
||||
class sun_tilemap_data,tile_pool,altas gpu_node_class;
|
||||
```
|
||||
|
||||
For faster access during rendering and shading, the `ShadowTileMapData` and `ShadowTileData` are converted into other data structure. This is done after all page allocation has run. The shaders responsible for this are `eevee_shadow_tilemap_finalize_comp.glsl` and `eevee_shadow_tilemap_amend_comp.glsl`.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
light["`***LightData***`"]
|
||||
tile["`***ShadowSamplingTile***`"]
|
||||
altas["`Shadow Atlas`"]
|
||||
render_view["`Render View`"]
|
||||
rendermap["`Render Map`"]
|
||||
|
||||
subgraph Shading
|
||||
light --> |tilemap_index| tile
|
||||
end
|
||||
|
||||
subgraph Rendering
|
||||
render_view --> |view_index| rendermap
|
||||
end
|
||||
|
||||
tile --> |page| altas
|
||||
rendermap --> |page| altas
|
||||
|
||||
classDef gpu_node_class stroke:#f66
|
||||
|
||||
class light,tile_atlas,tile,altas,render_view,rendermap gpu_node_class;
|
||||
```
|
||||
|
||||
## Page State
|
||||
|
||||
The atlas physical pages can be in 3 states: `freed`, `unused` and `used`. The page is not an object but just a location inside the atlas. The states are implicit from the page owner / location.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
tile_data["`***ShadowTileData***`"]
|
||||
page_heap["`Free Page Buffer`"]
|
||||
page_cache["`Cached Page Buffer`"]
|
||||
|
||||
tile_data --> |free| page_heap
|
||||
tile_data --> |unuse| page_cache
|
||||
page_cache --> |free| page_heap
|
||||
page_heap --> |allocate| tile_data
|
||||
page_cache --> |reuse| tile_data
|
||||
```
|
||||
|
||||
All pages start inside the *Free Page Buffer*.
|
||||
|
||||
If a page is allocated then it becomes owned by a `ShadowTileData` (which imply `used` state).
|
||||
|
||||
If a page gets out of view and still contains valid data, it becomes `unused` and is put into *Cached Page Buffer*.
|
||||
|
||||
If the *Free Page Buffer* is not enough to satisfy the needed allocation, cached pages are forced to be free.
|
||||
|
||||
The entry inside the *Cached Page Buffer* contains a reference to the previous owner `ShadowTileData`. The `ShadowTileData` also contains a reference to the *Cached Page Buffer* entry. This allows for all operations to be done in `O(1)` time.
|
||||
|
||||
## Execution
|
||||
|
||||
The shadow update loop runs for every frame for shading view (camera views or light probe capture views). It ensures all visible shadows are up to date, free unused pages, and allocate more resolution where needed.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Setup
|
||||
B[Tilemap Setup] --> C[Update Tagging] --> D[Usage Tagging] --> E[Tile Masking]
|
||||
end
|
||||
subgraph Allocation
|
||||
F[Page Free] --> G[Page Defrag] --> H[Page Allocate]
|
||||
end
|
||||
subgraph Rendering
|
||||
I[Create Render Views] --> L[Create Render Map]
|
||||
I --> J[Amend Shading Tilemap]
|
||||
I --> K[Page Clear]
|
||||
L & K --> M[Shadow Map Render]
|
||||
end
|
||||
A[Directional Bounds] --> B
|
||||
E --> F
|
||||
H --> I
|
||||
```
|
||||
|
||||
### Directional Bounds
|
||||
|
||||
Directional shadows needs to have a near plane to render correctly. This pass iterate over all bounding boxes in the scene and output the minimum near plane for each directional light that fits the whole scene.
|
||||
|
||||
### Setup
|
||||
This passes handle `ShadowTileData` updates and tagging.
|
||||
|
||||
The *Tilemap Setup* resets the tile states (see `init_tile_data()`) and shifts the `ShadowTileData` for directional shadows. It also sets pages dirty (with `SHADOW_DO_UPDATE`) if there was a light update.
|
||||
|
||||
Then *Update tagging* loops over the bounding boxes of updated shadow casters and tag the intersecting tile for update.
|
||||
|
||||
*Usage Tagging* scan all shadow receivers and reproject them onto the virtual shadow maps, and tag the corresponding tiles as used. For *Dithered* material objects this is done by scanning the depth buffer. For volumes, this loads the volume properties and only tag if there is any scattering. For *Blended* material, we ray-march the bounding volume of the object and tag all tiles along the ray.
|
||||
|
||||
The previous page tagging can request a lot of redundant information. For instance, for a same location in the virtual shadow map, multiple level of detail can be tagged. The *Tile Masking* phase untag the lower LOD tiles that are completely overlaped by higher LOD tiles. This is also where update throttle happens.
|
||||
|
||||
### Page allocation
|
||||
|
||||
Page allocation happens in 3 phases.
|
||||
|
||||
The *Page Free* phase frees unused pages, reclaim needed cached pages, and count the number of needed allocations.
|
||||
|
||||
Reclaiming the cached pages can leave the *Cached Page Buffer* in a non contiguous state, which is bad for the lockless insertion that *Page Free* also need to perform. That's why the *Page Defrag* phase defragments the buffer, leaving a contiguous array of cached pages.
|
||||
|
||||
If there are more allocations than free pages, the first pages inside the *Cached Page Buffer* are freed until there is enough free pages to satisfy all the allocations.
|
||||
|
||||
The *Page Allocation* phase simply pop the *Free Page Buffer* for all tiles marked as `used` but that have no physical page assigned.
|
||||
|
||||
We can run into the situation where there are more allocation needed than total available pages. In this case, the system output an error and the user needs to either reduce the amount of shadows or their precision in order to fix the issue. Note that this error is recoverable, it should never result in a crash. The resulting artifact of this situation is missing shadow tiles.
|
||||
|
||||
### Shadow rendering
|
||||
|
||||
The *Create Render Views* pass scans all tilemaps, extract updated LOD regions and create a render view for each. Up to 64 render views can be created. Exceeding this limit can cause missing shadow or shadow lag artifacts until everything is updated.
|
||||
|
||||
The pass outputs:
|
||||
- a list of views to render and their associated data `ShadowRenderView` and `ViewMatrices`.
|
||||
- a *Clear Tile Buffer* that lists all tiles to be cleared to max depth.
|
||||
- a *Tilemap Texture* which contains `ShadowSamplingTile`, a different version of `ShadowTileData` that allows `O(1)` access to all level of details.
|
||||
|
||||
The *Create Render Map* pass create a *Render Map* that maps regions of the render views to the shadow atlas pages. Having this structure bypasses the need to go through the whole `RenderView > Tilemap > TileData > Atlas Page` indirection (reducing 3 level of indirection to 1). It is generated by a separate pass because to reduce the shader complexity as it caused some issues on some platform.
|
||||
|
||||
The *Amend Shading Tilemap* allows to propagate tiles indirections across tilemaps. This is useful for shadow clipmaps where the LODs are contained in different tilemaps. This ensures `0(1)` lookup time for any LOD at any position. This is needed by shadow map tracing as the shadow map values can be queried outside of the requested position and these values usually exists in lower LODs.
|
||||
|
||||
For detail about the rendering itself, see [Shadow Pipeline](../pipelines/shadow.md).
|
||||
|
||||
After rendering, the *Shadow Atlas* depths represents the distances from the shadow origin for punctuals and as distance from near plane for directionals. It is ***not*** the usual Z depths used in shadow mapping. This simplifies the shadow tracing algorithm and position reconstruction.
|
||||
|
||||
## Update throttling
|
||||
|
||||
Updating a shadow map has a non negligeable cost. To keep the viewport and editing responsive, only a limited level of detail is updated per virtual shadow map for a single frame. We only update the lowest LOD first and progressively update the higher LODs if there is no updates.
|
||||
|
||||
# Shadow Map Tracing
|
||||
|
||||
EEVEE computes shadows by doing ray casting from the light towards the shading point. The ray traversal uses the virtual shadow map to find intersection. This allows (to some extent) plausible soft shadows at a reasonable cost.
|
||||
|
||||
The ray generation picks a random point on the light shape as ray origin. This step is not physically based at all as we don't consider the BSDF distribution for choosing this direction. We ensure that the ray is not below the horizon and that the end of the ray is not in regions of the shadow map that are likely to not be available (because of tagging) as it can create invalid shadowing (and thus noise).
|
||||
|
||||
The ray end point is jittered around the shading point in a similar way as for PCF filtering. This allows to hide the remaining aliasing artifacts. Note that we use optimal biases here to avoid self shadowing, but this only works if the shading normal is close to the geometric normal.
|
||||
|
||||
The backward tracing allows to keep track of the latest potential occluders and use heuristics to pass behind occluders that are too far away from the ray.
|
||||
|
||||
To simplify the extrapolation of the last known occluder, we create a basis around the ray and the shadow map origin. This allows us to reduce the intersection test to a 2D problem. In this configuration, the ray is intersecting geometry only if the extrapolated occluder crosses the ray.
|
||||
|
||||
# Shadow Map Jittering
|
||||
|
||||
This quality option randomize the position of the shadow map origin (or the angle, in the case of sun lights) for each render sample. The goal is to overcome the limitations of the single layer shadow map and the shadow map tracing. This technique is not physically based but it allows for very smooth shadows without aliasing. Note that this only jitter the shadow and not the shading.
|
||||
|
||||
For sphere light, we randomize the shadow center inside the ball with a special distribution that avoid biasing the shadow towards the center (see `sample_ball()`).
|
||||
|
||||
For sun light, we select a random point on the spherical cap sustented by the light and use it to setup our shadow. However, the lighting code will still use the original light direction.
|
||||
|
||||
This jittering is applied on the GPU, after the light culling phase. This is because we upload all GPU data after the sync phase, but this needs to amend the data that is alread for each render sample. The code for that is located in `eevee_light_shadow_setup_comp.glsl`.
|
||||
|
||||
@ -1,13 +1,16 @@
|
||||
- Classes
|
||||
- [Views](view.md)
|
||||
- Modules
|
||||
- [World](modules/world.md)
|
||||
- [Reflection Probes](modules/reflection_probes.md)
|
||||
- [Sphere Light-Probes](modules/lightprobe_sphere.md)
|
||||
- [Lookdev](modules/lookdev.md)
|
||||
- [Views](views/index.md)
|
||||
- [Capture](views/capture.md)
|
||||
- [Lookdev](views/lookdev.md)
|
||||
- [Pipeline](modules/pipeline.md)
|
||||
- [Film](modules/film.md)
|
||||
- [Shadow](modules/shadow.md)
|
||||
- [Pipelines](pipelines/index.md)
|
||||
- [Background](pipelines/background.md)
|
||||
- [Probe](pipelines/probe.md)
|
||||
- [World](pipelines/world.md)
|
||||
- [GPU Pipeline](gpu_pipeline.md)
|
||||
- [Deferred](pipelines/deferred.md)
|
||||
- [Shadow](pipelines/shadow.md)
|
||||
- [Render Passes](render_passes.md)
|
||||
|
||||
47
docs/features/eevee/pipelines/deferred.md
Normal file
47
docs/features/eevee/pipelines/deferred.md
Normal file
@ -0,0 +1,47 @@
|
||||
# Deferred Pipeline
|
||||
|
||||
This pipeline uses a technique commonly known as [deferred shading](https://learnopengl.com/Advanced-Lighting/Deferred-Shading).
|
||||
In a nutshell, a geometry pass outputs geometry data per pixel and then lighting is computed by separate shaders.
|
||||
|
||||
This decouples the material complexity from the lighting evaluation complexity, improving compilation time and performance.
|
||||
|
||||
Here is an overview of the deferred pipeline logic.
|
||||
|
||||
```mermaid
|
||||
%%{ init: { 'flowchart': { 'curve': 'basis' } } }%%
|
||||
flowchart TD
|
||||
subgraph Deferred Layer
|
||||
A[Depth Prepass] --> B[Material]
|
||||
B --> C[Direct Light]
|
||||
B --> D[Indirect Light]
|
||||
C & D --> E[SubSurface Scatter]
|
||||
E --> F[Combine]
|
||||
end
|
||||
```
|
||||
|
||||
|
||||
## Deferred Layers
|
||||
|
||||
Screen space transmission rays need access to the radiance of objects behind them. Materials tagged to use raytrace transmission will be put in a separate deferred layer.
|
||||
|
||||
Layers are rendered one after another and the whole deferred pipeline is run for each of them. The content of a layer can only affect itself and the content of subsequent layers.
|
||||
|
||||
> It is also possible that we add support for colored transparency for deferred material using this layering in the future (example use case would be ocean, windows).
|
||||
|
||||
## Polymorphic GBuffer
|
||||
|
||||
We use a polymorphic gbuffer whose layout can vary per pixel. The most common data are written through framebuffer attachement (fast) and write the remaining ones through arbitrary writes (slow).
|
||||
|
||||
The goal of this approach is to allow to vary the amount of data written per pixel and reduce the bandwidth usage for pixels that have simple material.
|
||||
|
||||
Here is a breakdown of the layout.
|
||||
|
||||
| | Header | Normal Data | Closure Data |
|
||||
|---|---|---|---|
|
||||
| Format | R16_UINT | RG16_UNORM | RGB10_A2_UNORM |
|
||||
| Framebuffer Output | Header | Normal x 1 | Closure Data x 2 |
|
||||
| Optional Image Output | N/A | Normal x 2 + Additional data | Closure Data x N |
|
||||
|
||||
Note that the use of arbitrary writes forces us to use early depth testing.
|
||||
|
||||
## Pixel Classification
|
||||
18
docs/features/eevee/pipelines/shadow.md
Normal file
18
docs/features/eevee/pipelines/shadow.md
Normal file
@ -0,0 +1,18 @@
|
||||
# Shadow Pipeline
|
||||
|
||||
All shadow casters subscribe to this pipeline. It is submitted once per view that needs shadows on every frame. This is because update detection is done one the GPU by [Shadow Module](../modules/shadow.md).
|
||||
|
||||
The rendering uses the multiview feature of the draw manager. The views are initialized on GPU and instances are generated only for valid views.
|
||||
|
||||
The framebuffer has no attachment and use an empty framebuffer configuration the size of a virtual shadow map (8192 x 8192 px). This is because rendering with a depth buffer of at most 64 x 8192 x 8192 px (~16GB of VRAM) is not feasible. Instead, we rasterize every polygon and use atomic min operations to populate the shadow atlas directly. This is why we need a separate tile *Page Clear* phase prior to render.
|
||||
|
||||
Since the size of the rendered regions can vary a lot (from 1x1 to 32x32 tiles wide) we leverage the multi viewport rendering capabilities of the GPU. With this extension, we can use a different viewport size for each view to avoid the rasterizer to spawn a lot of uneeded fragment shaders.
|
||||
The specs allows for 16 viewports which allows for a lot of variation in sizes. Note that one viewport can be reused by multiple views since we use the atomic operation to manually output to the correct region.
|
||||
|
||||
Each instance is generated with an associated `drw_view_id` (draw manager view), which allows to fetch the associated `ShadowRenderView`. Using this data we can output the geometry to the correct viewport and get the shadow atlas page indirection data inside the fragment shader.
|
||||
|
||||
The fragment shader outputs either the radial distance to the shadow cube center (for punctual shadows) or the distance to the near plane (for directional shadows).
|
||||
|
||||
For punctual, we do a software clip (using `discard`) before a certain distance from the shadow origin to avoid shadow casters inside sphere lights to cast shadow outside the sphere.
|
||||
|
||||
The output is written dirrectly at the physical page location inside the *Shadow Atlas* texture using `atomicMin` operations. The page are cleared at `FLT_MAX`. This works because we only write positive float bits and the binary representation of increasing positive float is also increasing.
|
||||
36
docs/features/eevee/view.md
Normal file
36
docs/features/eevee/view.md
Normal file
@ -0,0 +1,36 @@
|
||||
# View
|
||||
|
||||
Views are containers for persistent per view data (e.g. Raytracing persistent buffers, Persistent culling data, etc...). The `render()` method of a view will call one or multiple pipelines to compute the view pixels. Then the result is outputed to a module data (e.g. `Film`, `SphereProbeModule` etc...).
|
||||
|
||||
## Main View
|
||||
|
||||
This view allows to render the output render or viewport. It is composed of at least one `ShadingView`. For panoramic rendering, it can use up to 6 `ShadingView` in order to cover the full spherical domain as a cubemap.
|
||||
|
||||
The `ShadingView` uses most of the modules and pipelines.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
F(Background Pipeline) --> A(Deferred Pipeline) --> B(Forward Pipeline) --> C(Motion Blur) --> D(Depth Of Field) --> |Output| E(Film)
|
||||
```
|
||||
|
||||
## Capture View
|
||||
|
||||
A view to capture sphere probes. It can render either the world alone or the scene.
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
F(Background Pipeline) -->A(Deferred Pipeline) --> |Output| E(Cubemap Face Target)
|
||||
```
|
||||
|
||||
> There is a naming confusion error with this view. The `CaptureView` is used to render sphere probes but the `CapturePipeline` is used to turn the scene into surfels for volume probe. This is very confusing and should be cleaned up.
|
||||
|
||||
See [SphereProbe Module](modules/lightprobe_sphere.md) for more detailed informations.
|
||||
|
||||
## Lookdev View
|
||||
|
||||
This view is used to render the Lookdev HDRI Spheres. The spheres are rendered using an orthographic projection but with accurate positioning inside the scene. We render the spheres as if they were on the camera near plane with a relatively small radius.
|
||||
Separating the lookdev sphere rendering from the *Main View* ensures that they will never be occluded and have no influence on the scene.
|
||||
|
||||
> At the time of writting, this view is *not* `LookdevView` but `LookdevModule::Sphere` and part of the `LookdevModule`. This is against design and needs some cleanup to move it to `eevee_view.cc`.
|
||||
|
||||
See [LookDev Module](modules/lookdev.md) for more detailed informations.
|
||||
@ -1,18 +0,0 @@
|
||||
# CaptureView
|
||||
|
||||
A view to capture reflection probes from the scene.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
class CaptureView {
|
||||
render_world()
|
||||
render_probes()
|
||||
}
|
||||
```
|
||||
|
||||
The CaptureView asks the `ReflectionProbeModule` if any reflection probe
|
||||
needs to be rerendered. If that is the case it will be rendered and
|
||||
or updated.
|
||||
|
||||
See [ReflectionProbeModule](../modules/reflection_probes.md) for detailed
|
||||
information.
|
||||
@ -1,3 +0,0 @@
|
||||
# Views
|
||||
|
||||
Views are used to render a pipeline with a specific view.
|
||||
@ -1,6 +0,0 @@
|
||||
# LookdevView
|
||||
|
||||
The lookdev view is used to generate an ortographical view from the viewport
|
||||
to render the Lookdev HDRI Spheres. The spheres are rendered on the near
|
||||
clip plane of the view. This ensures that the spheres will always be in view
|
||||
and should not consider the actual size of the scene.
|
||||
@ -1,6 +1,7 @@
|
||||
# Extension Listing API
|
||||
|
||||
The specification for all the Extension Listing API versions. Note that Blender should be able to keep supporting previous API versions.
|
||||
The specification for all the Extension Listing API versions.
|
||||
Note that Blender should be able to keep supporting previous API versions.
|
||||
|
||||
| Version | Blender Version Initial | Blender Version Final |
|
||||
| ----------------- | -------------------------------------------- | -------------------------------------------- |
|
||||
|
||||
@ -15,12 +15,12 @@
|
||||
"type": "add-on",
|
||||
"archive_size": 856650,
|
||||
"archive_hash": "sha256:3d2972a6f6482e3c502273434ca53eec0c5ab3dae628b55c101c95a4bc4e15b2",
|
||||
"archive_url": "https://extensions.blender.org/add-ons/blender-kitsu/0.1.0/download/",
|
||||
"archive_url": "https://extensions.blender.org/add-ons/blender-kitsu/0.1.5-alpha+f52258de/download/",
|
||||
"blender_version_min": "4.2.0",
|
||||
"maintainer": "Blender Studio",
|
||||
"tags": ["Pipeline"],
|
||||
"license": ["SPDX:GPL-3.0-or-later"],
|
||||
"website": "http://extensions.blender.org/add-ons/blender-kitsu/",
|
||||
"website": "https://extensions.blender.org/add-ons/blender-kitsu/",
|
||||
"schema_version": "1.0.0"
|
||||
}
|
||||
]
|
||||
@ -36,9 +36,17 @@
|
||||
| <b>data</b> | List of dictionaries with the extensions information. | `{"id"="example_extension", ...}` |
|
||||
|
||||
NOTE:
|
||||
The content of data depends on the [schema](../schema/index.md) for the respective extension.
|
||||
The content of data depends on the [schema](../schema/index.md) for the respective extension. And similar to it,
|
||||
the optional fields (e.g., ``blender_version_max``) are either to have a value or should be omitted from the entries.
|
||||
|
||||
The best way to generate this JSON file is by using [command-line](https://docs.blender.org/manual/en/dev/extensions/getting_started.html#command-line) tools.
|
||||
For the official Extensions Platform, the ``website`` value is the page of the extension in the online platform.
|
||||
Even if the manifest points to the project specific website.
|
||||
|
||||
---
|
||||
|
||||
Generate this JSON file by using the
|
||||
[command-line](https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html)
|
||||
tools.
|
||||
|
||||
## Changelog
|
||||
* Initial version.
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
# Extensions
|
||||
|
||||
[Extensions Platform](https://extensions.blender.org) integration and design topics.
|
||||
[Extensions Platform](https://extensions.blender.org/) integration and design topics.
|
||||
|
||||
NOTE:
|
||||
Extensions are planned to be released with Blender 4.2.
|
||||
* [Manifest Schema](schema/index.md)
|
||||
* [Listing API](api_listing/index.md)
|
||||
* [Moderation](moderation/index.md)
|
||||
211
docs/features/extensions/moderation/canned_responses.md
Normal file
211
docs/features/extensions/moderation/canned_responses.md
Normal file
@ -0,0 +1,211 @@
|
||||
# Canned Responses
|
||||
|
||||
These are to be used as a start point, combined with some extra explanations if needed.
|
||||
|
||||
!!! NOTE
|
||||
These responses are to ensure extensions adhere to:
|
||||
|
||||
- [Terms of Service](https://extensions.blender.org/terms-of-service/)
|
||||
- [Add-on Guidelines](../../../handbook/addons/guidelines/index.md)
|
||||
|
||||
## General
|
||||
|
||||
### Low Quality
|
||||
|
||||
This extension does not seem to provide enough value for users for it to be included.
|
||||
|
||||
```
|
||||
This extension does not seem to provide enough value for users for it to be included.
|
||||
```
|
||||
|
||||
### Broken Add-on
|
||||
|
||||
The add-on is not working at the moment, please
|
||||
[Install from Disk](https://docs.blender.org/manual/en/dev/editors/preferences/extensions.html)
|
||||
to test if everything is working well.
|
||||
|
||||
```
|
||||
The add-on is not working at the moment, please
|
||||
[Install from Disk](https://docs.blender.org/manual/en/dev/editors/preferences/extensions.html)
|
||||
to test if everything is working well.
|
||||
```
|
||||
|
||||
### Includes an Updater
|
||||
|
||||
Add-ons should not be including their own updating functionality as this is is handled by
|
||||
Blender directly now.
|
||||
|
||||
```
|
||||
Add-ons should not be including their own updating functionality as this is is handled by
|
||||
Blender directly now.
|
||||
```
|
||||
|
||||
### Uses an Updater Without Consent
|
||||
|
||||
This add-on makes use of an updater which connects to the internet without user consent
|
||||
(or setting the corresponding `permission`).
|
||||
|
||||
```
|
||||
This add-on makes use of an updater which connects to the internet without user consent
|
||||
(or setting the corresponding `permission`).
|
||||
```
|
||||
|
||||
### Request External Components
|
||||
|
||||
Extensions should not require any external functional components (other than Blender itself)
|
||||
that need to be downloaded from elsewhere.
|
||||
See the Extensions Platform [Terms of Service](https://extensions.blender.org/terms-of-service/).
|
||||
|
||||
If you can't (or don't want) to change your extension to adapt to it, you can
|
||||
[self-host](https://docs.blender.org/manual/en/dev/extensions/getting_started.html#third-party-extension-sites)
|
||||
it without this restriction.
|
||||
|
||||
```
|
||||
Extensions should not require any external functional components (other than Blender itself)
|
||||
that need to be downloaded from elsewhere.
|
||||
See the Extensions Platform [Terms of Service](https://extensions.blender.org/terms-of-service/).
|
||||
|
||||
If you can't (or don't want) to change your extension to adapt to it, you can
|
||||
[self-host](https://docs.blender.org/manual/en/dev/extensions/getting_started.html#third-party-extension-sites)
|
||||
it without this restriction.
|
||||
```
|
||||
|
||||
## Code Quality
|
||||
|
||||
### Includes Python's Cache
|
||||
|
||||
This extension bundles byte-code compiled code `__pycache__`,
|
||||
which could differ from the original code in ways we can't easily validate and isn't necessary.
|
||||
|
||||
This should be removed, we recommend to use the extension `build` command
|
||||
which wont include these files. e.g. `blender -c extension build`.
|
||||
see:
|
||||
[Extension Command Line Arguments
|
||||
](https://docs.blender.org/manual/en/dev/advanced/command_line/extension_arguments.html#command-line-args-extension-build)
|
||||
|
||||
```
|
||||
This extension bundles byte-code compiled code `__pycache__`,
|
||||
which could differ from the original code in ways we can't easily validate and isn't necessary.
|
||||
|
||||
This should be removed, we recommend to use the extension `build` command
|
||||
which wont include these files. e.g. `blender -c extension build`.
|
||||
see:
|
||||
[Extension Command Line Arguments
|
||||
](https://docs.blender.org/manual/en/dev/advanced/command_line/extension_arguments.html#command-line-args-extension-build)
|
||||
```
|
||||
|
||||
### Backslash Path Separators
|
||||
|
||||
This add-on uses backslash literals as path separators which won't work on Linux or macOS.
|
||||
|
||||
Use `os.sep` for the native path separator or utility functions such as `os.path.join`
|
||||
or the `pathlib` module.
|
||||
|
||||
```
|
||||
This add-on uses backslash literals as path separators which won't work on Linux or macOS.
|
||||
|
||||
Use `os.sep` for the native path separator or utility functions such as `os.path.join`
|
||||
or the `pathlib` module.
|
||||
```
|
||||
|
||||
### Hard Coded Data-Block Names
|
||||
|
||||
This add-on makes error prone assumptions about data block names in the users file:
|
||||
e.g. `bpy.data.worlds["World"]`
|
||||
|
||||
```
|
||||
This add-on makes error prone assumptions about data block names in the users file:
|
||||
e.g. `bpy.data.worlds["World"]`
|
||||
```
|
||||
|
||||
### Uses `__name__` ID for Preferences
|
||||
|
||||
Using `__name__` to lookup add-on preferences is no longer valid.
|
||||
See how to [use `__package__`
|
||||
](https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#user-preferences-and-package)
|
||||
instead.
|
||||
|
||||
```
|
||||
Using `__name__` to lookup add-on preferences is no longer valid.
|
||||
See how to [use `__package__`
|
||||
](https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#user-preferences-and-package)
|
||||
instead.
|
||||
```
|
||||
|
||||
### Manipulates Python's Module Loading
|
||||
|
||||
This add-on manipulates Python's module search to expose modules:
|
||||
Bundled modules must either be:
|
||||
|
||||
* Loaded as sub-modules, or in the case of modules from the
|
||||
[Python Package Index (pypi.org)](https://pypi.org).
|
||||
* Included as
|
||||
[Python Wheels](https://docs.blender.org/manual/en/latest/advanced/extensions/python_wheels.html)
|
||||
(see the [Guidelines](https://developer.blender.org/docs/handbook/addons/guidelines/)).
|
||||
|
||||
```
|
||||
This add-on manipulates Python's module search to expose modules:
|
||||
Bundled modules must either be:
|
||||
|
||||
* Loaded as sub-modules, or in the case of modules from the
|
||||
[Python Package Index (pypi.org)](https://pypi.org).
|
||||
* Included as
|
||||
[Python Wheels](https://docs.blender.org/manual/en/latest/advanced/extensions/python_wheels.html)
|
||||
(see the [Guidelines](https://developer.blender.org/docs/handbook/addons/guidelines/)).
|
||||
```
|
||||
|
||||
### Assumes Add-ons Directory is Writable
|
||||
|
||||
This add-on assumes the add-ons directory is writable (which may not be the case),
|
||||
use `bpy.utils.extension_path_user` to create a writable path for the extension.
|
||||
|
||||
See the [Guidelines](https://developer.blender.org/docs/handbook/addons/guidelines/) and
|
||||
[Local Storage](https://docs.blender.org/manual/en/latest/advanced/extensions/addons.html#local-storage).
|
||||
|
||||
```
|
||||
This add-on assumes the add-ons directory is writable (which may not be the case),
|
||||
use `bpy.utils.extension_path_user` to create a writable path for the extension.
|
||||
|
||||
See the [Guidelines](https://developer.blender.org/docs/handbook/addons/guidelines/) and
|
||||
[Local Storage](https://docs.blender.org/manual/en/latest/advanced/extensions/addons.html#local-storage).
|
||||
```
|
||||
|
||||
### Manifest Should Have `platforms` (Has Binary Files)
|
||||
|
||||
Binary files are included but the manifest doesn't define supported `platforms`.
|
||||
|
||||
```
|
||||
Binary files are included but the manifest doesn't define supported `platforms`.
|
||||
```
|
||||
|
||||
### Manifest Shouldn't Have `platforms` (No Binary Files)
|
||||
|
||||
The `blender_manifest.toml` defines `platforms`
|
||||
even though the extension doesn't seem to include any platform specific code.
|
||||
|
||||
This will make the extension incompatible with other platforms & architectures.
|
||||
|
||||
Unless platforms is needed to exclude incompatible platforms, it should be removed.
|
||||
|
||||
```
|
||||
The `blender_manifest.toml` defines `platforms`
|
||||
even though the extension doesn't seem to include any platform specific code.
|
||||
|
||||
This will make the extension incompatible with other platforms & architectures.
|
||||
|
||||
Unless platforms is needed to exclude incompatible platforms, it should be removed.
|
||||
```
|
||||
|
||||
### Obfuscated Code
|
||||
|
||||
This extension violates the [Terms of Service](https://extensions.blender.org/terms-of-service/):
|
||||
> no obfuscated code or byte code is allowed.
|
||||
|
||||
Example: `split_3D044 = split_17838.split(factor=0.5, align=True)`
|
||||
|
||||
```
|
||||
This extension violates the [Terms of Service](https://extensions.blender.org/terms-of-service/):
|
||||
> no obfuscated code or byte code is allowed.
|
||||
|
||||
Example: `split_3D044 = split_17838.split(factor=0.5, align=True)`
|
||||
```
|
||||
129
docs/features/extensions/moderation/guidelines.md
Normal file
129
docs/features/extensions/moderation/guidelines.md
Normal file
@ -0,0 +1,129 @@
|
||||
# Guidelines
|
||||
|
||||
Process and recommendations to help with extension submit approval review.
|
||||
This can also guide extension authors to make sure their submissions are
|
||||
up to the highest standards.
|
||||
|
||||
## General
|
||||
|
||||
1. Make sure the [Terms of Service](https://extensions.blender.org/terms-of-service/) are respected.
|
||||
([example](https://extensions.blender.org/approval-queue/cadbase-library/))
|
||||
|
||||
0. Check if it works in Blender (run some basic functionality)
|
||||
* Most often the add-on is just not working, since it was poorly converted into an extension
|
||||
without testing ([example](https://extensions.blender.org/approval-queue/nd/#activity-159)).
|
||||
* Sometimes the add-on was never updated for 4.2 specific API
|
||||
([example](https://extensions.blender.org/approval-queue/dragengine-tools/#activity-151)).<br>
|
||||
Refer to the breaking API changes:
|
||||
[4.0](https://developer.blender.org/docs/release_notes/4.0/python_api/#breaking-changes) /
|
||||
[4.1](https://developer.blender.org/docs/release_notes/4.1/python_api/#breaking-changes).
|
||||
|
||||
0. Check the manifest, common problems:
|
||||
* Permissions are not correct (`files` is expected for most I/O add-ons).
|
||||
* Optional arguments left in with default values (it shouldn't happen anymore since the guide was updated)
|
||||
|
||||
0. Python: Make sure there is no auto-updater on the code
|
||||
([example](https://extensions.blender.org/approval-queue/textify/#activity-126)).
|
||||
|
||||
0. Python: pip dependencies should be
|
||||
[bundled as wheels or vendorized](https://docs.blender.org/manual/en/dev/extensions/addons.html#bundle-dependencies).
|
||||
|
||||
0. Python: If using `network` permission, the add-on is expected to check for `bpy.app.online_access`.
|
||||
|
||||
0. Interface: When possible, it is nice to share some advice on following UI's guidelines
|
||||
([example](https://extensions.blender.org/approval-queue/y-projectionnode-form-camera-f1/#activity-165)).
|
||||
|
||||
0. Check the overall quality of the images.
|
||||
|
||||
0. Make sure there are no heavy image (`.gif` images in particular)
|
||||
on the image description, making the page massive to load.
|
||||
|
||||
0. Make sure the author is the owner/maintainer of the extension.
|
||||
|
||||
0. Make sure the add-on is self-contained.
|
||||
* This is the most delicate one and if in doubt ask on the
|
||||
[#extension-moderators](https://blender.chat/channel/extensions-moderators) channel.
|
||||
* It should not have functionality which is extended by external software.
|
||||
* It should not depend on external servers (`localhost` is fine).
|
||||
|
||||
## Violations in Code
|
||||
|
||||
1. Check all uses of `__file__`, this relates to two common mis-uses of this:
|
||||
* Manually constructing paths to add to `sys.path` and import modules into
|
||||
the global module name-space.
|
||||
Instead, sub-modules or wheels must be used.
|
||||
* Constructing paths to write to, when it must not be assumed the add-on directory is writable.
|
||||
Instead `bpy.utils.extension_path_user` must be used.
|
||||
|
||||
0. Check all uses of `open`, especially writing files
|
||||
to ensure the script is writing to a valid location.
|
||||
|
||||
0. Check all uses of `__name__`, for legacy add-ons this matches the add-on ID.
|
||||
For extensions `__package__` is used for the add-on identifier,
|
||||
e.g. `context.preferences.addons[__package__]` will return the add-on.
|
||||
The following expression is a common mistake: `context.preferences.addons[__name__].preference`
|
||||
|
||||
0. Check for all uses of the `sys` module.
|
||||
In general it should only be considered read-only.
|
||||
Direct manipulation or assignment of any of it's values is a hint that the extension
|
||||
may be making global changes that impact other modules.
|
||||
|
||||
0. Check there are no hard coded repository module names `user_repository` or `blender_org`.<br>
|
||||
Also check the literal `bl_ext` is never used as this is practically always a bad sign that an
|
||||
extension is either manipulating another extensions or not using relative imports when it should.
|
||||
|
||||
0. Check access to `bpy.context.window_manager.keyconfigs.addon`
|
||||
accounts for None (in background mode).
|
||||
|
||||
0. Check online access.
|
||||
* Search for imports: `requests` & `urllib`.
|
||||
* Search for `http` literal.
|
||||
* Double check all access first checks `bpy.app.online_access`
|
||||
and sending any data to a 3rd party is an explicit user action.
|
||||
|
||||
## Code Quality
|
||||
|
||||
Some extensions have low quality code, while not violating any rules,
|
||||
it's likely to cause problems and can be noted in review.
|
||||
|
||||
1. Check for back-slash characters (`\`) use as path separators
|
||||
(that aren't used for escaping or line continuations).<br>
|
||||
These wont work on Linux or macOS.
|
||||
|
||||
0. Check direct access to Blender data: `bpy.data.[a-z_]+\.`
|
||||
This often hints at weak logic, for example:
|
||||
* `bpy.data.scenes[bpy.context.scene.name]`
|
||||
This can be a bug as two data-blocks may have the same name when one is from a library.
|
||||
* `bpy.data.worlds["World"]`
|
||||
Hard coded data-block names may not exist.
|
||||
In general it's a bad sign if scripts are assuming data-blocks with special names exist.
|
||||
|
||||
0. Check access of `bpy.data.objects`.
|
||||
This is rarely useful, in most cases the current scenes objects should be accessed instead.
|
||||
|
||||
0. Incorrect Quoting (Python expression)
|
||||
|
||||
When generating Python expressions...
|
||||
|
||||
`file.write('open("' + path + '")'` should be:<br>
|
||||
`file.write('open(' + repr(path) + ')'`
|
||||
|
||||
_Or use the `repr` formatting specifiers for `str.format` or percentage-formatting:
|
||||
`{!r}` or `%r` respectively._
|
||||
|
||||
0. Incorrect Quoting (Blender's Data-Paths)
|
||||
|
||||
`insert_keyframe('"pose.bones["' + bone.name + '"].property')` where `bone.name` should be<br>
|
||||
`bpy.utils.escape_identifier(bone.name)`
|
||||
|
||||
0. Incorrect Quoting (Command Line Arguments)
|
||||
|
||||
`os.system('some_command --path "' + filepath + '"')` should be:<br>
|
||||
`os.system(shlex.join(["some_command", "--path", filepath])`
|
||||
|
||||
0. Run a linter on all scripts:
|
||||
`find "." -iname "*.py" | xargs ruff check --output-format=concise --ignore=E402,E741,E731`
|
||||
|
||||
_While this doesn't need to pass without warnings: large numbers of unused imports,
|
||||
undefined variables or invalid syntax are a bad sign and might hint at inclusion of
|
||||
outdated/unused code._
|
||||
14
docs/features/extensions/moderation/index.md
Normal file
14
docs/features/extensions/moderation/index.md
Normal file
@ -0,0 +1,14 @@
|
||||
# Moderation
|
||||
|
||||
To help with extensions moderation:
|
||||
|
||||
* Read over the [Guidelines](guidelines.md).
|
||||
* Visit the [Approval Queue](https://extensions.blender.org/approval-queue/).
|
||||
* Help testing and reviewing the Awaiting Review extensions (ideally in a safe virtual environment).
|
||||
* For any questions, join the team on the [#extension-moderators](https://blender.chat/channel/extensions-moderators) channel.
|
||||
* Remember to be polite and assume good intentions all around :)
|
||||
|
||||
---
|
||||
|
||||
* [Canned Responses](canned_responses.md)
|
||||
* [Guidelines](guidelines.md)
|
||||
@ -15,35 +15,70 @@ maintainer = "Developer name <email@address.com>"
|
||||
# Supported types: "add-on", "theme"
|
||||
type = "add-on"
|
||||
|
||||
# Optional: add-ons can list which resources they will require:
|
||||
# * "files" (for access of any filesystem operations)
|
||||
# * "network" (for internet access)
|
||||
# * "clipboard" (to read and/or write the system clipboard)
|
||||
# * "camera" (to capture photos and videos)
|
||||
# * "microphone" (to capture audio)
|
||||
# permissions = ["files", "network"]
|
||||
## Optional link to documentation, support, source files, etc
|
||||
# website = "https://extensions.blender.org/add-ons/my-example-package/"
|
||||
|
||||
# Optional link to documentation, support, source files, etc
|
||||
# website = "http://extensions.blender.org/add-ons/my-example-package/"
|
||||
|
||||
# Optional list defined by Blender and server, see:
|
||||
# https://docs.blender.org/manual/en/dev/extensions/tags.html
|
||||
tags = ["Animation", "Sequencer"]
|
||||
## Optional list defined by Blender and server, see:
|
||||
## https://docs.blender.org/manual/en/dev/advanced/extensions/tags.html
|
||||
# tags = ["Animation", "Sequencer"]
|
||||
|
||||
blender_version_min = "4.2.0"
|
||||
# Optional: maximum supported Blender version
|
||||
## Optional: Blender version that the extension does not support, earlier versions are supported.
|
||||
## This can be omitted and defined later on the extensions platform if an issue is found.
|
||||
# blender_version_max = "5.1.0"
|
||||
|
||||
# License conforming to https://spdx.org/licenses/ (use "SPDX: prefix)
|
||||
# https://docs.blender.org/manual/en/dev/extensions/licenses.html
|
||||
# https://docs.blender.org/manual/en/dev/advanced/extensions/licenses.html
|
||||
license = [
|
||||
"SPDX:GPL-2.0-or-later",
|
||||
]
|
||||
# Optional: required by some licenses.
|
||||
## Optional: required by some licenses.
|
||||
# copyright = [
|
||||
# "2002-2024 Developer Name",
|
||||
# "1998 Company Name",
|
||||
# ]
|
||||
|
||||
## Optional list of supported platforms. If omitted, the extension will be available in all operating systems.
|
||||
## Other supported platforms: "windows-arm64", "macos-x64"
|
||||
# platforms = ["windows-x64", "macos-arm64", "linux-x64"]
|
||||
|
||||
## Optional: bundle 3rd party Python modules.
|
||||
## https://docs.blender.org/manual/en/dev/advanced/extensions/python_wheels.html
|
||||
# wheels = [
|
||||
# "./wheels/hexdump-3.3-py3-none-any.whl",
|
||||
# "./wheels/jsmin-3.0.1-py3-none-any.whl",
|
||||
# ]
|
||||
|
||||
## Optional: add-ons can list which resources they will require:
|
||||
## * files (for access of any filesystem operations)
|
||||
## * network (for internet access)
|
||||
## * clipboard (to read and/or write the system clipboard)
|
||||
## * camera (to capture photos and videos)
|
||||
## * microphone (to capture audio)
|
||||
##
|
||||
## If using network, remember to also check `bpy.app.online_access`
|
||||
## https://docs.blender.org/manual/en/dev/advanced/extensions/addons.html#internet-access
|
||||
##
|
||||
## For each permission it is important to also specify the reason why it is required.
|
||||
## Keep this a single short sentence without a period (.) at the end.
|
||||
## For longer explanations use the documentation or detail page.
|
||||
#
|
||||
# [permissions]
|
||||
# network = "Need to sync motion-capture data to server"
|
||||
# files = "Import/export FBX from/to disk"
|
||||
# clipboard = "Copy and paste bone transforms"
|
||||
|
||||
## Optional: build setting.
|
||||
## https://docs.blender.org/manual/en/dev/advanced/extensions/command_line_arguments.html#command-line-args-extension-build
|
||||
# [build]
|
||||
# paths_exclude_pattern = [
|
||||
# "/.git/",
|
||||
# "__pycache__/",
|
||||
# ]
|
||||
|
||||
# This was added automatically when building and must not be included in source manifest files.
|
||||
[build.generated]
|
||||
platforms = ["windows-x64", "macos-arm64", "linux-x64", "windows-arm64", "macos-x64"]
|
||||
```
|
||||
|
||||
### Required values
|
||||
@ -64,11 +99,13 @@ license = [
|
||||
|
||||
| Field | Description | Example |
|
||||
| ----- | ----------- | ------- |
|
||||
| <b>blender_version_max</b> | Maximum version of Blender that can run this. | `"4.2.0"` |
|
||||
| <b>website</b> | Website for the extension. | `"http://extensions.blender.org/add-ons/my-example-extension/"` |
|
||||
| <b>blender_version_max</b> | Blender version that the extension does not support, earlier versions are supported. | `"5.1.0"` |
|
||||
| <b>website</b> | Website for the extension. | `"https://extensions.blender.org/add-ons/my-example-extension/"` |
|
||||
| <b>copyright</b> | Some licenses require a copyright, copyrights must be "Year Name" or "Year-Year Name". | `["2002-2024 Developer Name", "1998 Company Name"]` |
|
||||
| <b>permissions</b> | Add-ons can list which resources they require. The available options are ["files", "network", "clipboard", "camera", "microphone"]. | `["files"]` |
|
||||
| <b>tags</b> | List of tags. See the [list of available tags](https://docs.blender.org/manual/en/dev/extensions/tags.html). | `["Animation", "Sequencer"]` |
|
||||
| <b>platforms</b> | List of supported platforms. If ommitted, the extension will be available in all operating systems. The available options are ["windows-x64", "windows-arm64", "macos-x64", "macos-arm64", "linux-x64"] | `["windows-amd64"]` |
|
||||
| <b>wheels</b> | List of relative file-paths [Python Wheels](https://docs.blender.org/manual/en/dev/extensions/python_wheels.html). | `["./wheels/jsmin-3.0.1-py3-none-any.whl"]` |
|
||||
| <b>permissions</b> | Add-ons can list which resources they require. The available options are: *files*, *network*, *clipboard*, *camera*, *microphone*. Each permission should be followed by an explanation (short single-sentence with no end punctuation). | `network = "Need to sync motion-capture data to server"` |
|
||||
|
||||
NOTE:
|
||||
All the values present in the manifest file must be filled
|
||||
@ -76,5 +113,10 @@ All the values present in the manifest file must be filled
|
||||
If you don't want to set one of the optional values just exclude it from the manifest altogether.
|
||||
|
||||
|
||||
### Build generated
|
||||
`[build.generated]`
|
||||
|
||||
When building with `blender -c extension build --split-platforms` Blender will populate the `build.generated` section with the specific platforms used for this building.
|
||||
|
||||
## Changelog
|
||||
* Initial version.
|
||||
|
||||
@ -13,8 +13,8 @@ drawing the user interface to the screen. These low level APIs include:
|
||||
* Font drawing
|
||||
* Widget drawing
|
||||
|
||||
Drawing viewport require a different approach compared to regular screens in
|
||||
order to be able to optimize the performance of the 3d viewport. We call name
|
||||
Drawing the viewport requires a different approach compared to regular screens
|
||||
in order to be able to optimize the performance of the 3d viewport. We call
|
||||
this the draw manager. The draw manager is used for drawing
|
||||
|
||||
* EEVEE
|
||||
|
||||
@ -24,3 +24,4 @@
|
||||
- [Tools](tools/index.md)
|
||||
- [RenderDoc](tools/renderdoc.md)
|
||||
- [Shader Builder](tools/shader_builder.md)
|
||||
- [Shader printf](tools/printf.md)
|
||||
|
||||
@ -5,3 +5,4 @@ Here is a list of commonly used tools.
|
||||
|
||||
- Validate shaders when compiling Blender using [Shader builder](./shader_builder.md)
|
||||
- GPU debugging [Renderdoc](./renderdoc.md)
|
||||
- Use [Shader printf](./printf.md) to debug values and codeflow inside shaders without external tools.
|
||||
48
docs/features/gpu/tools/printf.md
Normal file
48
docs/features/gpu/tools/printf.md
Normal file
@ -0,0 +1,48 @@
|
||||
# Shader printf
|
||||
|
||||
This debugging feature is built-in blender shader system. It allows the usage of `printf` directly inside shader code.
|
||||
|
||||
For example:
|
||||
```glsl
|
||||
printf("gl_FragCoord %f %f\n", gl_FragCoord.x, gl_FragCoord.y);
|
||||
```
|
||||
|
||||
> NOTE:
|
||||
> This feature is only available in debug mode by default. This is to prevent shipping with `printf` inside shaders since their presence triggers some expensive synchronization.
|
||||
|
||||
You can force enable it in release mode by setting `GPU_FORCE_ENABLE_SHADER_PRINTF` to 1.
|
||||
|
||||
The size of the output buffer can be adjusted by changing `GPU_SHADER_PRINTF_MAX_CAPACITY`.
|
||||
|
||||
It is important to limit the amount of threads that call the `printf`, otherwise the buffer limit might be easily exceeded.
|
||||
This can be done using this snippet (to be adapted for each the shader type):
|
||||
```glsl
|
||||
#ifdef GPU_FRAGMENT_SHADER
|
||||
if (all(equal(ivec2(gl_FragCoord.xy), ivec2(100)))) {
|
||||
printf("Here\n");
|
||||
}
|
||||
#endif
|
||||
```
|
||||
|
||||
Some limitations:
|
||||
- The formating options are limited to `%u`, `%x`, `%d` and `%f`.
|
||||
- The output is async and will only happen when either the `gpu::Context` is unbinded or when `GPU_render_step` is called.
|
||||
- If buffer overflows, only an error message is printed.
|
||||
|
||||
> NOTE:
|
||||
> These limitations should ultimately be fixed or offer a way to workaround them.
|
||||
|
||||
## Implementation details
|
||||
The format strings are stored into dictionary on CPU and indexed by their hash. Only the hash of the format and the data is written by the shader inside the `printf_buf`. The CPU does the data formatting.
|
||||
|
||||
The `printf` support is implemented by doing these steps:
|
||||
- On startup:
|
||||
- For each `printf(` occurences:
|
||||
- Extract the format string and store it inside a dictionary.
|
||||
- Replace `printf` by `print_header` and `print_value` calls.
|
||||
- Add `gpu_print` resource info to shaders that contains `printf` calls.
|
||||
- On each redraw:
|
||||
- If a `printf` is detected in the shader codebase:
|
||||
- Create the `printf_buf` at context binding.
|
||||
- Bind the `printf_buf` at *every* call to `GPU_shader_bind`.
|
||||
- Readback, print and delete the `printf_buf` at context unbind.
|
||||
@ -28,7 +28,7 @@ Internally, drawings are represented as [CurvesGeometry](../objects/curves.md#cu
|
||||
|
||||
### Internal Attributes
|
||||
|
||||
Here are attributes that are used by Grease Pencil.
|
||||
Here is a list of attributes that are used by Grease Pencil internally.
|
||||
|
||||
| Name | Domain | Optional | Description |
|
||||
| -------------- | ------- | ---------------- | ------------------------------------ |
|
||||
@ -36,11 +36,19 @@ Here are attributes that are used by Grease Pencil.
|
||||
| `radius` | `POINT` | :material-check: | The radii of the points (in meters). The default radius is 1 cm.|
|
||||
| `opacity` | `POINT` | :material-check: | The opacities of the points (0 to 1). The default opacity is 1. |
|
||||
| `vertex_color` | `POINT` | :material-check: | The color of the points. This is mixed on top of the base material color based on the alpha. By default, the alpha is 0. |
|
||||
| `rotation` | `POINT` | :material-check: | This is the rotation of a texture on the point. |
|
||||
| `delta_time` | `POINT` | :material-check: | Written while drawing. The time since the start of the stroke in seconds. Used by the build modifier to "replay" how the stroke was draw. |
|
||||
| `.selection` | `POINT` | :material-check: | The selection state of the point. True if the point is selected, false otherwise. |
|
||||
| `cyclic` | `CURVE` | :material-check: | True for curves that are cyclic and false otherwise. Default is false. |
|
||||
|`material_index`| `CURVE` | :material-check: | A material index for this curve. Defaults to the default material. |
|
||||
| `start_cap` | `CURVE` | :material-check: | A cap type for the start of the curve. `0 = ROUND`, `1 = FLAT`. Default is `ROUND`. |
|
||||
| `end_cap` | `CURVE` | :material-check: | A cap type for the end of the curve. `0 = ROUND`, `1 = FLAT`. Default is `ROUND`. |
|
||||
| `softness` | `CURVE` | :material-check: | Used to render a soft gradient from the center line of the stroke to the edge. |
|
||||
| `curve_type` | `CURVE` | :material-check: | The type (`CurveType`) of the curve. `POLY`, `BEZIER`, `CATMUL_ROM`, or `NURBS`. |
|
||||
| `aspect_ratio` | `CURVE` | :material-check: | Value used to scale the x and y of textures on vertices. The aspect ratio is x / y where y is clamped to a minimum of 1e-7. |
|
||||
| `fill_opacity` | `CURVE` | :material-check: | Opacity value used for the fills. |
|
||||
| `fill_color` | `CURVE` | :material-check: | The fill color. The alpha value is used to mix in the base material color (0 means only the material color is used). |
|
||||
| `init_time` | `CURVE` | :material-check: | Written while drawing. An approximate timestamp at which this stroke was created. Used by the build modifier to "replay" how strokes were drawn. |
|
||||
|
||||
### Drawing References
|
||||
|
||||
|
||||
@ -40,12 +40,12 @@ point.</b>
|
||||
**Do**: "Determine how the geometry end factor is mapped to a spline"*
|
||||
- Do **not** use more than a couple of lines, try to stick with two or
|
||||
three.
|
||||
- Use full sentences (periods and commas are allowed).
|
||||
- Do **not** end the description with a period, unless there are multiple sentences.
|
||||
- It's fine to mention examples of situations where you might use the
|
||||
tool.
|
||||
- Do **not** document default values; these can change and are hard to
|
||||
keep updated.
|
||||
- Do **not** use the described term to explained itself.
|
||||
- Do **not** use the described term to explain itself.
|
||||
\* *Limit Surface
|
||||
**Don't:** "Put vertices at the limit surface"
|
||||
**Do**: "Place vertices at the surface that would be produced with
|
||||
|
||||
@ -1,154 +1,145 @@
|
||||
# Icons
|
||||
|
||||
There are multiple types of icons in Blender:
|
||||
There are multiple types and classes of icons in Blender:
|
||||
|
||||
1. `blender_icons.svg` - Main icon sheets.
|
||||
2. `alert_icons.svg` - Large icons for dialogs (warning, info, etc).
|
||||
3. `prvicons.svg` - Used for large preview of documents, drives, etc.
|
||||
4. `brushicons/` - A folder with PNG images for the built-in brushes
|
||||
(sculpt, Grease Pencil, etc)
|
||||
5. `toolbar.blend` - Tool icons (as in the toolbar).
|
||||
1. UI Icons - Small icons used throughout the interface.
|
||||
2. Alert Icons - Large icons used in dialogs and confirmations.
|
||||
3. File System Icons - Large icons to represent file system items while in File Browser thumbnail view.
|
||||
4. Miscellaneous Icons - Large icons and images used for specialized purposes.
|
||||
5. Brush Icons - PNG images used for the built-in brushes (sculpt, Grease Pencil, etc)
|
||||
6. Tool Icons - Medium-sized icons used for tool, in the 3D View Toolbar
|
||||
|
||||
The source files are stored in `release/datafiles/`.
|
||||
## UI Icons
|
||||
|
||||
## blender_icons
|
||||
|
||||
|
||||
{style="width:640px;"}
|
||||
These are the small icons used throughout the interface, including in menus and on buttons.
|
||||
|
||||
These are the small icons used throughout the interface, including
|
||||
menus.
|
||||
|
||||
The source is a vector SVG document containing a grid of icons. A Python
|
||||
script exports this file into two PNG images using Inkscape, then crops
|
||||
them into individual bitmaps as .dat files using Blender.
|
||||
|
||||
This results in two bitmap sizes, 16x16 and 32x32. We use the former
|
||||
when the interface is at 1x or smaller, and the larger for all other
|
||||
sizes. But this means that our resolution maxes out at normal resolution
|
||||
on high-dpi displays. We may consider replacing both sets with one at
|
||||
64x64.
|
||||
These are scalable vector SVG images found in the `datafiles\icons_svg` folder. During compile time these source files are embeded into the Blender executable as XML data. At runtime they are treated similarly to text glyphs in that they are rasterized to the requested bitmap size on first use and then saved to our text system's glyph cache. This allows them to be shown optimally at any size.
|
||||
|
||||
### Design
|
||||
|
||||
These icons are generally 14x14 within a 16x16 pixel grid. Features
|
||||
should be aligned to the grid and should not be smaller or narrower than
|
||||
one unit. These are designed to be viewed at very small sizes so are
|
||||
purposefully simple and chunky.
|
||||
Generally these icons will be a design comprising 1400x1400 units in
|
||||
a document of size 1600x1600, using a grid size of 100 units. Although
|
||||
SVG documents are unitless, these are considered "pixel" units in
|
||||
programs like Inkscape.
|
||||
|
||||
If in doubt just copy the style in use in the source document. See the
|
||||
More specifically, all the icons have one grid (100 units) of padding on
|
||||
a document that is no taller than 1600 units, but of any width. Narrow
|
||||
designs should be just wide enough for the content plus one grid of padding
|
||||
to the left and right. Short designs should similarly be just as tall as
|
||||
needed plus one unit of spacing above and below.
|
||||
|
||||
In most uses the icons will be drawn centered in their available space. If
|
||||
you have multiple icons that need to line up with each other but differ in
|
||||
size, and aren't centered, then give each a document width that allows this.
|
||||
But otherwise there should be no more than one grid unit of empty space
|
||||
around icons. Although this design seems less convenient than a fixed document
|
||||
size, this allows for better centering as resolution scale increases, non-square
|
||||
large designs, and allows for the inference of actual design extents.
|
||||
|
||||
For icons meant for general (small) usage, the minimum feature size is one
|
||||
grid (100 units) and lines should be exactly that wide, aligned to the grid.
|
||||
These are meant to be viewed at very small sizes so are purposefully simple
|
||||
and chunky. These designs can include curves and circles, but these should
|
||||
also line up the grid as best as possible.
|
||||
|
||||
The icons should comprise full white areas and strokes over transparency.
|
||||
Areas of lesser importance should have _lowered opacity_. This way the icons
|
||||
can be recolored (and even made black) and will keep the same contrast.
|
||||
|
||||
If in doubt just copy the style and construction of an existing icon. See the
|
||||
[Human Interface Guidelines](human_interface_guidelines/icons.md) on best
|
||||
practices to design Blender icons. Before adding new icons please
|
||||
consult with members of the
|
||||
[User Interface module](https://projects.blender.org/blender/blender/wiki/Module:-User-Interface).
|
||||
|
||||
### Requirements
|
||||
### Technical details and toolchain considerations
|
||||
This use of SVG icons directly within Blender is new to us. Therefore some details
|
||||
and recommendations may change as we use them.
|
||||
|
||||
The following has been tested on GNU/Linux (Ubuntu), and on Windows
|
||||
through WSL (Windows Subsystem for Linux).
|
||||
All of the current icons have been optimized to be as small as possible (by
|
||||
a program called SVG Cleaner, a GUI for [svgcleaner](https://github.com/RazrFalcon/svgcleaner)).
|
||||
This results in dramatically smaller file sizes.
|
||||
|
||||
- To modify or add icons you need to know [how to build
|
||||
Blender](../../handbook/building_blender/index.md)
|
||||
- [Inkscape](https://inkscape.org/) 1.0+
|
||||
- On Debian/Ubuntu/WSL: `apt install inkscape` (Ubuntu 20.04 LTS
|
||||
ships with Inkscape 0.9x, you need to get it from the
|
||||
`ppa:inkscape.dev/stable` PPA).
|
||||
- Blender
|
||||
- Needs to be accessible by running `blender`
|
||||
- Python 3+
|
||||
However, since these icons are white on transparent they can be impossible to see
|
||||
when you first load them into a program like Inkscape. Because of that we have added
|
||||
in the bare minimum boilerplate to allow them to show a contrasting background and grid lines.
|
||||
This can be copied from an existing icon, but the following shows the start of a typical
|
||||
icon XML:
|
||||
|
||||
### How to edit icons
|
||||
|
||||
- Open `blender_icons.svg` in Inkscape
|
||||
- Edit or add an icon in one of the empty rows, try to put it in a place
|
||||
where it makes sense (a row of similar icons), see `UI_icons.h` for
|
||||
reference.
|
||||
- Run `make icons`
|
||||
- Compile Blender (you can use the faster `make lite` to quickly
|
||||
iterate through versions)
|
||||
```
|
||||
<svg height="1600" viewBox="0 0 1600 1600" width="1600" xmlns="http://www.w3.org/2000/svg" xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"><sodipodi:namedview pagecolor="#303030" showgrid="true"><inkscape:grid id="grid5" units="px" spacingx="100" spacingy="100" color="#4772b3" opacity="0.2" visible="true" /></sodipodi:namedview><g fill="#fff"><g ... </g></g></svg>
|
||||
```
|
||||
Eventually we will probably creating icons with specific id names on groups so you
|
||||
don't want to run an optimization that shortens IDs. It is also possible that we
|
||||
may one day add our own namespace for custom attributes.
|
||||
|
||||
### How to add a new icon
|
||||
|
||||
- Add the icon to `blender_icons.svg`
|
||||
- Place the icon in a group named after the coordinates in the grid
|
||||
(see others for reference)
|
||||
- Respect the alphabetical order already present in the list
|
||||
- Open `/source/blender/editors/include/UI_icons.h`
|
||||
- Find the section that makes more sense for the icon you want to add.
|
||||
- e.g. if you want to add an icon for the Sequencer, look for icons
|
||||
starting with `SEQ_`.
|
||||
- Find a `DEF_ICON_BLANK(<number>)` available and replace it with:
|
||||
- `DEF_ICON(EXAMPLE_NAME)`
|
||||
- Some icons are colored by the theme based on their category.
|
||||
|
||||
- `DEF_ICON_SCENE(<name>)`
|
||||
- `DEF_ICON_COLLECTION(<name>)`
|
||||
- `DEF_ICON_OBJECT(<name>)`
|
||||
- `DEF_ICON_OBJECT_DATA(<name>)`
|
||||
- `DEF_ICON_MODIFIER(<name>)`
|
||||
- `DEF_ICON_SHADING(<name>)`
|
||||
- `DEF_ICON_FOLDER(<name>)`
|
||||
|
||||
<br/>
|
||||
E.g. If you are adding a new modifier, use `DEF_ICON_MODIFIER(<name>)` instead of `DEF_ICON`.
|
||||
|
||||
For other categories read the header of `UI_icons.h`
|
||||
|
||||
Your new icon will be accessible just like regular icons:
|
||||
|
||||
- `layout.prop(sc, "example_prop", text="My Prop", icon='EXAMPLE_NAME')`
|
||||
|
||||
### Committing the icon
|
||||
|
||||
- Add the icon name to
|
||||
`/source/blender/editors/datafiles/CMakeLists.txt`
|
||||
- Use lowercase, and place it in the same order than in `UI_icons.h`
|
||||
- `blender_icons.svg`
|
||||
- Make sure that the changes only add the icon and nothing else (no
|
||||
header changes, metatags, etc).
|
||||
|
||||
For reference, [check out this
|
||||
commit](https://developer.blender.org/rB57c41a9c633e4c48aff716d85a0977e4b39a8bdd)
|
||||
or [this
|
||||
commit](https://developer.blender.org/rBce71357711eb0d79916045f1e67523af21b1791e)
|
||||
that add icons.
|
||||
- Add the SVG file to the `release/datafiles/icons_svg` folder
|
||||
- Name should be lowercase, **not** start with "icon", no spaces (underscore instead)
|
||||
- Add the file name to /source/blender/editors/datafiles/CMakeLists.txt
|
||||
- In a list called SVG_SRC. The order does not matter, but respect the current alphabetical order.
|
||||
- Just the file name, in lowercase, without any trailing ".svg".
|
||||
- Define the icon in source/blender/editors/include/UI_icons.hh
|
||||
- Anywhere between `DEF_ICON(NONE)` and `DEF_ICON_BLANK(LAST_SVG_ITEM)`
|
||||
- The order doesn't matter, but find somewhere that make sense. Keep on/off pairs together.
|
||||
- Most icons should be defined with `DEF_ICON` but some are colored by the theme based on their category.
|
||||
- `DEF_ICON_SCENE(<name>)`
|
||||
- `DEF_ICON_COLLECTION(<name>)`
|
||||
- `DEF_ICON_OBJECT(<name>)`
|
||||
- `DEF_ICON_OBJECT_DATA(<name>)`
|
||||
- `DEF_ICON_MODIFIER(<name>)`
|
||||
- `DEF_ICON_SHADING(<name>)`
|
||||
- `DEF_ICON_FOLDER(<name>)`
|
||||
- Compile Blender.
|
||||
- Your new icon will be accessible just like regular icons.
|
||||
- `layout.prop(sc, "example_prop", text="My Prop", icon='EXAMPLE_NAME')`
|
||||
|
||||
## Alert Icons
|
||||
|
||||
{width=640px}
|
||||
|
||||
|
||||
These are large icons (256x256) for use in dialog and alert boxes.
|
||||
These are large icons for use in dialogs, confirmations, info, and alert boxes.
|
||||
|
||||
- Edit: `alert_icons.svg`
|
||||
- Run `make icons`
|
||||
- Result: `alert_icons.png`
|
||||
- Rebuild Blender.
|
||||
These are made and used identically to other UI icons, but are designed to be used at larger sizes.
|
||||
They should still be made within the same 1600x1600 document, should have a slightly less coarse design, with line
|
||||
widths about 75 units and feature sizes no smaller than about 50 units.
|
||||
- cancel_large.svg - Stop symbol to indicate error conditions or important warnings
|
||||
- warning_large.svg - Hazard symbol used for most normal warning conditions
|
||||
- question_large.svg - Question mark
|
||||
- info_large.svg - Used for informational text.
|
||||
|
||||
## File Browser Icons
|
||||
|
||||
{style="width:640px;"}
|
||||
|
||||
|
||||
These are large icons (256x256) for use in the File Browser.
|
||||
These are large icons for use in the File Browser. They represent file system items while in thumbnail views.
|
||||
|
||||
- Edit: `prvicons.svg`
|
||||
- Run `make icons`
|
||||
- Result: `prvicons.png`
|
||||
- Rebuild Blender.
|
||||
These are made and used identically to other UI icons, but are designed to be used at larger sizes.
|
||||
They should still be made within the same 1600x1600 document, should have a less coarse design, with minimum
|
||||
feature sizes (like line widths) about half a grid (50 units) and no smaller than about a quarter (25 units).
|
||||
- file_large.svg - File system items (a smaller icon is added to indicate file type)
|
||||
- file_folder_large.svg - Folder/Directory
|
||||
- file_parent_large.svg - Parent of current folder
|
||||
- disc_large.svg - Optical drives
|
||||
- disk_drive_large.svg - Local internal storage
|
||||
- external_drive_large.svg - Local externally attached storage
|
||||
- network_drive_large.svg - Remove network shares
|
||||
|
||||
## brushicons
|
||||
## Miscellaneous Icons
|
||||
|
||||
{style="width:640px;"}
|
||||
These are large icons used for specialized purpose.
|
||||
|
||||
Brush icons are simple PNG files that can be edited using any image
|
||||
editing software like [GIMP](https://www.gimp.org/) or
|
||||
[Krita](https://www.krita.org/).
|
||||
These are made and used identically to other UI icons, but are designed to be used at larger sizes. These
|
||||
are still designed for the same grid size, but do not have any feature size limitations. Non-square items
|
||||
should still fit vertically within the 1600 unit high document, but can be any width.
|
||||
- blender_large.svg - Blender logo symbol
|
||||
- blender_logo_large.svg - Blender text logo
|
||||
|
||||
These images can be found in `/release/datafiles/brushicons/`.
|
||||
Assigning images to brushes is done manually as part of
|
||||
`startup.blend`.
|
||||
## Tool Icons
|
||||
|
||||
## toolbar.blend
|
||||
|
||||
{style="width:640px;"}
|
||||
|
||||
|
||||
This type of icon, used for toolbar tools, is larger and scalable.
|
||||
|
||||
|
||||
@ -10,6 +10,7 @@
|
||||
- Rendering
|
||||
- [Cycles](cycles/)
|
||||
- [EEVEE](eevee/)
|
||||
- [Workbench](workbench/)
|
||||
- [Compositor](compositor/)
|
||||
- [Sequencer](sequencer/)
|
||||
- [Render Pipeline](render_pipeline/)
|
||||
|
||||
4
docs/features/workbench/img/shadow_volume_manifold.svg
Normal file
4
docs/features/workbench/img/shadow_volume_manifold.svg
Normal file
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 75 KiB After Width: | Height: | Size: 75 KiB |
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 20 KiB After Width: | Height: | Size: 20 KiB |
10
docs/features/workbench/index.md
Normal file
10
docs/features/workbench/index.md
Normal file
@ -0,0 +1,10 @@
|
||||
# Workbench
|
||||
|
||||
Workbench is the draw engine that powers the solid display mode.
|
||||
|
||||
## Design principles
|
||||
|
||||
Workbench is meant to be very simple and optimized for large scene. Readability of the scene and reactivity being the main concern.
|
||||
|
||||
## Design Documents
|
||||
- [Shadow](shadow.md)
|
||||
43
docs/features/workbench/shadow.md
Normal file
43
docs/features/workbench/shadow.md
Normal file
@ -0,0 +1,43 @@
|
||||
# Shadow
|
||||
|
||||
Workbench supports casting a single shadow from an arbitrary shadow direction. The shadow is artificial as it is not connected to any of the built-in lights. It only darken the overall intensity of the shading in shadowed regions.
|
||||
|
||||
This directional shadow is rendered using [shadow volumes](https://en.wikipedia.org/wiki/Shadow_volume).
|
||||
|
||||
We implement both the depth-fail and depth-pass variants and switch between them depending on camera position.
|
||||
Note that depth-pass do not need to render the volume caps and thus are faster.
|
||||
|
||||
Also note that winding order for generated geometry matters, as the stencil operation is not the same for front and back-faces.
|
||||
|
||||
## Manifold Meshes
|
||||
|
||||
For manifold meshes, every face backfacing the light will always be occluded by front faces that are closer to the light. This is because the mesh is closed. This mean we can skip extruding them.
|
||||
|
||||
To generate the shadow volume, we extrude each patch of faces that faces the light, along the light direction.
|
||||
|
||||
|
||||
|
||||
- Each edge where adjacent faces have different facing state is extruded into a quad, to form one of the volume sides.
|
||||
- Each face facing the light is duplicated and positioned at both ends of the volume, creating the volume caps.
|
||||
|
||||
## Non-Manifold Meshes
|
||||
|
||||
For non-manifold meshes, the previous assumption about backfaces doesn't hold. So we have to extrude all surfaces.
|
||||
|
||||
We split the surface into patch of faces that has the same facing state. This is because shadow volumes have to be all manifold.
|
||||
|
||||
|
||||
|
||||
- Each edge where adjacent faces have different facing state is extruded twice into two quad, as it belongs to 2 different volumes.
|
||||
- Each edge with no neighbor (border edge) is also extruded but only once, as it belongs to 1 volume.
|
||||
- All faces are duplicated and positioned at both ends of the volume, to create the volume caps. Light back-facing faces have their winding reversed to have consistent winding per volume.
|
||||
|
||||
## Implementation Detail
|
||||
|
||||
Transparent surfaces do not cast shadows.
|
||||
|
||||
The detph-fail method is forced for non-manifold as it is incompatible with them.
|
||||
|
||||
The depth-pass and depth-fail render passes are both populated for manifold objects, with the GPU culling selecting between both.
|
||||
|
||||
The volume extrusion is done directly on the GPU using the position vertex buffer. The drawcall uses the primitive expansion API to generate a number of primitives for each input primitive. This is alike to a geometry shader but is faster and is compatible cross graphic API. See the documentation for more detail.
|
||||
@ -1,131 +1,61 @@
|
||||
# Requirements for contributed Scripts
|
||||
<!--
|
||||
NOTE(@ideasman42): This doesn't cover bundled (core) add-ons since these are not indented
|
||||
to be the place where new add-ons are submitted.
|
||||
If necessary we could document conventions for core add-ons separately from extensions.
|
||||
Arguably `extension.blender.org` should document it's own policy outside of developer docs,
|
||||
however these conventions are generally good community guidelines which would be good
|
||||
for other (non Blender) repositories to follow.
|
||||
-->
|
||||
|
||||
To prepare your script for submission into the Blender Add-ons Catalog
|
||||
(to be distributed along with Blender) your script must
|
||||
# Guidelines for Add-ons
|
||||
|
||||
- contain [ Add-on Meta
|
||||
Information](../addon_meta_info.md) in a `bl_info` dictionary.
|
||||
- define register() and unregister() functions.
|
||||
- be documented on an associated [Wiki
|
||||
Page](https://en.blender.org/index.php/Dev:Py/Scripts/Guidelines/Addons/wikipage)
|
||||
in the Blender Wiki
|
||||
- be evaluated and approved by another Blender Developer
|
||||
- pass the Flake8 / other PEP 8 checker Tool For Style Guide Enforcement
|
||||
- be compatible with the latest Blender release (for help updating
|
||||
scripts to run on 2.8x, consult this [page (Work in
|
||||
Progress)](../../../release_notes/2.80/python_api/index.md))
|
||||
- Inclusion of binary data-files is to be avoided (`.blend` files for
|
||||
example).
|
||||
To prepare your add-on for submission as an extension to Blenders official repository,
|
||||
add-ons must:
|
||||
|
||||
## Style Recommendations
|
||||
<!--
|
||||
NOTE(@ideasman42): keep this list short and to the point.
|
||||
Issues relating to code-quality, formatting, naming etc can be handled elsewhere.
|
||||
-->
|
||||
|
||||
- **Respect Blender's "Allow Online Access":**<br>
|
||||
Not making connections to the internet when `bpy.app.online_access` is False.
|
||||
|
||||
**The flake8 Tool**
|
||||
- **Not Interfere with Other Add-ons:**<br>
|
||||
Making changes to other add-ons is forbidden (installing/updating/removing etc).<br>
|
||||
If the extension depends on another, an error can be shown when accessing functionality
|
||||
that requires the other extension.
|
||||
|
||||
The flake8 tool is currently used as a style checker for Python code.
|
||||
However, other PEP 8 tools can be used instead, taking into account some
|
||||
scripting specifics / style exemptions used for convenience. flake8
|
||||
incorporates several scripts into one - providing additional
|
||||
functionality like checking for unused variables. To install flake8,
|
||||
follow the *Quickstart* instructions from the *Flake8 Checker* link at
|
||||
the bottom of the page, so it is available system wide. The tool can be
|
||||
run from the command line or setup to run from a specific IDE. To get
|
||||
flake8 running in a specific editor, please consult that editor's
|
||||
documentation.
|
||||
- **Be Self Contained:**<br>
|
||||
Add-ons must not install Python modules, PIP packages, Python-wheels etc.<br>
|
||||
If some additional software required that cannot be bundled, this can be run by the user.
|
||||
|
||||
**Here is the list of Style recommendations for Blender Add-ons**:
|
||||
- **Bundle Modules:**<br>
|
||||
Add-ons must only load modules into the packages name-space (typically as sub-modules).<br>
|
||||
Manipulating Blender's module loading such as changing the module search path or inserting
|
||||
modules directly into the global module dictionary is forbidden
|
||||
as this makes global changes outside the add-ons name-space.<br>
|
||||
Extensions may include 3rd party module as python-wheels.
|
||||
|
||||
- Line length must not exceed 120 characters
|
||||
- Use 4 spaces for indentation. No mixing of tabs and spaces allowed.
|
||||
- Two lines gap between functions and classes, one maximum between
|
||||
blocks inside a function/class
|
||||
- Spaces around operators
|
||||
- No trailing spaces (at the end of a line or in empty lines of code)
|
||||
- If possible, avoid single scripts longer than 1000 lines. Consider
|
||||
breaking them in sub-modules in a folder structure imported from an
|
||||
**__init__.py** instead.
|
||||
- All *significant functions*<sup>1</sup>, classes, and functions within
|
||||
classes should have a docstring explaining
|
||||
- what they do,
|
||||
- which parameters they receive,
|
||||
- which parameters they return.
|
||||
- Comments and variable names in US English.
|
||||
- *Constant*<sup>2</sup> variable names all upper case.
|
||||
- No reliance on deprecated parts of the Blender/Python API.
|
||||
- **Support "System" (read-only) installation:**<br>
|
||||
Add-ons must not write files in their own directories since "System"
|
||||
repositories may be used on read-only file-systems.<br>
|
||||
Use `bpy.utils.extension_path_user(__package__, create=True)` to create a local directory
|
||||
extensions may use to store user local files.
|
||||
|
||||
|
||||
<sup>1</sup>: *Significant Functions*: For our purposes, a significant
|
||||
function requiring a docstring is a function that's purpose and
|
||||
functionality will not be obvious to a python programmer unfamiliar with
|
||||
the code at first glance. Even fairly simple functions should have a
|
||||
docstring if they are more then a few lines
|
||||
|
||||
<sup>2</sup>: *Constants*: Python has no constants, this refers to
|
||||
variables that do not change in the script. For some example names: PI,
|
||||
EUL for a small number, RAD_TO_DEG, IDENTITY_MATRIX4X4.
|
||||
|
||||
## Criteria to be checked before evaluation
|
||||
|
||||
Below you find a list of evaluation properties which should apply to
|
||||
your Script. Please make sure that your Script matches the points nicely
|
||||
before you contact a reviewer. This will save a lot of time for
|
||||
everybody and it will give you a good chance to get your Work published
|
||||
quickly:
|
||||
|
||||
- Robustness
|
||||
- Maintainability (readability)
|
||||
- Correctness and completeness
|
||||
- Functionality
|
||||
- Documentation
|
||||
- Consistency (the interface and functionality should try to match with
|
||||
the existing feel and conventions of Blender).
|
||||
|
||||
## How to get your Script published in Blender
|
||||
|
||||
If you are finally ready to publish your addon on the Blender Foundation
|
||||
servers, get started by reading the formal [Process to Submit
|
||||
Addons](../index.md) to Blender repositories.
|
||||
|
||||
## Special case: Using Custom Icons and images
|
||||
|
||||
If you want to use custom icons in your addon (available from Blender
|
||||
2.75), you also need to observe these guidelines:
|
||||
|
||||
- Do not use these for advertising, logos, or other non-functional use
|
||||
cases.
|
||||
- Use a minimal number of custom icons. This helps to keep Blender's
|
||||
interface uniform and uncluttered.
|
||||
- Only use custom images in a way that is compatible with how the rest
|
||||
of Blender works - they should seem like part of the default interface
|
||||
we provide for everyone.
|
||||
- Only use the feature within the context and UI of your own Add-on. You
|
||||
cannot rely on other add-ons to have this already preloaded. This
|
||||
feature also does not allow replacing of the default icons.
|
||||
- Do not force preview image creation outside of the add-on dir, except
|
||||
when explicitly asked for by the user in the UI.
|
||||
- The default icon size in Blender is 32x32 and for previews it's
|
||||
256x256. Your images will be scaled to fit these sizes on their
|
||||
maximum side.
|
||||
> NOTE: **Hint**
|
||||
> While these are requirements for `extensions.blender.org`,
|
||||
> we recommend following them for add-ons hosted elsewhere
|
||||
> because they help ensure add-ons work in a verity of configurations.
|
||||
|
||||
# See also
|
||||
|
||||
## Addons usage
|
||||
- [Blender Manual for
|
||||
Add-ons](https://docs.blender.org/manual/en/dev/editors/preferences/extensions.html)<br>
|
||||
General information about add-on **usage**.
|
||||
|
||||
[Blender Manual page on addons](https://docs.blender.org/manual/en/dev/editors/preferences/addons.html)
|
||||
General information about addon **usage**
|
||||
- [Blender Manual for Creating Extensions &
|
||||
Add-ons](https://docs.blender.org/manual/en/4.2/advanced/extensions/index.html)<br>
|
||||
General information about add-on **usage**.
|
||||
|
||||
## Coding style
|
||||
|
||||
[Style Guide for Python Code](http://www.python.org/dev/peps/pep-0008/)
|
||||
Recommended coding conventions for submitted Python code
|
||||
|
||||
<!-- -->
|
||||
|
||||
[Flake8 Checker](https://pypi.python.org/pypi/flake8)
|
||||
A tool to check Python code to see if it conforms to the PEP 8 style
|
||||
conventions listed in the link just above this one
|
||||
|
||||
<!-- -->
|
||||
|
||||
[PEP8 online check](http://pep8online.com/)
|
||||
An Online PEP 8 Python code checker
|
||||
- [Style Guide for Python Code](http://www.python.org/dev/peps/pep-0008/)<br>
|
||||
Recommended coding conventions for submitted Python code
|
||||
|
||||
@ -17,8 +17,6 @@ This helps to find people with certain hardware, to confirm bug reports or help
|
||||
| [Antonio Vazquez](https://projects.blender.org/antoniov) | Intel Core i9-9900K (8-Core) | NVIDIA GeForce RTX 2080TI | 32GB | Windows 10 | Wacom Intuos 3 |
|
||||
| [Ankit Meel](https://projects.blender.org/ankitm) | Intel Core i5-5350U (2-Core) | Intel HD Graphics 6000 | 8GB | macOS Monterey (12.1) | |
|
||||
| [Ankit Meel](https://projects.blender.org/ankitm) | Intel Core i7-9750H (6-core) | AMD Radeon Pro 5300M | 16GB | macOS Big Sur (11.4) | |
|
||||
| [Aras Pranckevicius](https://projects.blender.org/aras_p) | Apple M1 Max | Apple M1 | 32GB | macOS Monterey (12.3) | |
|
||||
| [Aras Pranckevicius](https://projects.blender.org/aras_p) | AMD Ryzen 5950X (16-Core) | NVIDIA GeForce RTX 3080 | 32GB | Windows 10 | |
|
||||
| [Bastien Montagne](https://projects.blender.org/mont29) | AMD Ryzen 7 4800HS (8-Core) | AMD Renoir integrated | 48GB | Debian testing | |
|
||||
| [Brecht Van Lommel](https://projects.blender.org/brecht) | AMD Ryzen 2990wx (32-Core) | NVIDIA Quadro RTX A6000 | 48GB | Ubuntu 20.04 | |
|
||||
| [Brecht Van Lommel](https://projects.blender.org/brecht) | Apple M1 | Apple M1 | 16GB | macOS 11 | |
|
||||
@ -30,6 +28,7 @@ This helps to find people with certain hardware, to confirm bug reports or help
|
||||
| [Germano Cavalcante](https://projects.blender.org/mano-wii) | Apple M1 | Apple-designed integrated graphics | 8GB | macOS Big Sur (11.5.2) - ARM 64 Bits | |
|
||||
| [Germano Cavalcante](https://projects.blender.org/mano-wii) | AMD Ryzen 7 5800H | NVIDIA GeForce RTX 3060 Laptop GPU/PCIe/SSE2 | 16GB | Windows 11 | |
|
||||
| [Hans Goudey](https://projects.blender.org/hooglyboogly) | AMD Ryzen 9 7950X | Ryzen 6700XT | 64GB | Fedora 38 | |
|
||||
| [Harley Acheson](https://projects.blender.org/Harley) | Intel Core i9-13900K (24-Core) | NVIDIA GeForce RTX 4080 | 32GB | Windows 11 | |
|
||||
| [Himanshi Kalra](https://projects.blender.org/Calra) | Intel Core I5-8250U (4-Core) | Intel UHD Graphics 620 && NVIDIA GeFornce MX150 | 8GB | Windows 11 | Wacom One |
|
||||
| [Jacques Lucke](https://projects.blender.org/JacquesLucke) | AMD Ryzen 9 3900X (12-Core) | AMD Radeon RX 5700 | 48GB | Fedora | |
|
||||
| [Jeroen Bakker](https://projects.blender.org/Jeroen-Bakker) | Intel Core i7-6700 (4-Core) | AMD Radeon RX 5700 | 64GB | Linux pop-OS | |
|
||||
@ -50,11 +49,11 @@ This helps to find people with certain hardware, to confirm bug reports or help
|
||||
| [Pratik Borhade](https://projects.blender.org/PratikPB2123) | AMD Ryzen 7 5800H (8-Core) | NVIDIA GeForce RTX 3050 | 16GB | Windows 11 | |
|
||||
| [Robert Gützkow](https://projects.blender.org/rjg) | Intel Core i7-6850K | NVIDIA GeForce GTX 1080 Ti | 32GB | Windows 10 | Wacom Intuos CTH-490 |
|
||||
| [Robert Gützkow](https://projects.blender.org/rjg) | Intel Core i7-4800MQ | Intel® HD-Graphic 4600 | 8GB | Linux (Ubuntu) | |
|
||||
| [Richard Antalik](https://projects.blender.org/iss) | AMD Ryzen 9 3950X (16-Core) | NVIDIA GeForce RTX 3060 | 64GB | Windows 10 | |
|
||||
| [Richard Antalik](https://projects.blender.org/iss) | AMD Ryzen 9 3950X (16-Core) | AMD Radeon RX 550 | 48GB | Xubuntu | |
|
||||
| [Richard Antalik](https://projects.blender.org/iss) | Intel Core i9 (10-Core) | AMD Radeon Pro 5700 XT 16GB | 64GB | macOS 12.6 | |
|
||||
| [Richard Antalik](https://projects.blender.org/iss) | AMD Ryzen 7 4700U (8-Core) | Integrated | 16GB | Windows 10 | |
|
||||
| [Sergey Sharybin](https://projects.blender.org/Sergey) | Intel Core i9-11900K (8-Core) | NVIDIA Quadro RTX 6000 | 64GB | Debian Testing / Windows 10 | 3Dconnexion Space Navigator 3D Mouse |
|
||||
| [Thomas Dinges](https://projects.blender.org/ThomasDinges) | AMD Ryzen 7 3700X (8-Core) | AMD Radeon RX 5500 XT | 32GB | Windows 10 | |
|
||||
| [Thomas Dinges](https://projects.blender.org/ThomasDinges) | Apple M1 Max | Apple M1 Max | 64GB | macOS 12.3 | |
|
||||
| [Thomas Dinges](https://projects.blender.org/ThomasDinges) | Intel Core i5-6200U (2-Core) | Intel HD Graphics 520 | 8GB | Windows 10 | |
|
||||
| [Wu Yiming](https://projects.blender.org/ChengduLittleA) | Intel Core i9-13900K (32-Threads) | NVIDIA RTX 4070 12GB | 64GB | Ubuntu 22.04 / Windows 11 | Wacom Cintiq Pro 24 / Pro Pen / Art Pen / Saitek x56 |
|
||||
| [Wu Yiming](https://projects.blender.org/ChengduLittleA) | Intel Core i7-4910MQ (8-Threads) | NVIDIA Quadro K5100M 8GB | 32GB | Ubuntu 22.04 | same pen deivce as above |
|
||||
@ -67,3 +66,6 @@ And here is a list of hardware in use by active volunteers.
|
||||
| [Alaska](https://projects.blender.org/Alaska) | AMD Ryzen 9 5950X (16-core) | NVIDIA GeForce RTX 4090 | 64GB | Windows 11 | HP Reverb G2 WMR/VR Headset |
|
||||
| [Alaska](https://projects.blender.org/Alaska) | AMD Ryzen 5 5600 (6-core) | AMD RX 7800XT/Intel Arc A750 | 32GB | Windows 11/Linux | |
|
||||
| [Alaska](https://projects.blender.org/Alaska) | Apple M1 Pro (8-core) | Apple M1 Pro | 16GB | macOS 14 | XDR/HDR display |
|
||||
| [Aras Pranckevicius](https://projects.blender.org/aras_p) | Apple M1 Max | Apple M1 | 32GB | macOS Sonoma (14.1) | |
|
||||
| [Aras Pranckevicius](https://projects.blender.org/aras_p) | AMD Ryzen 5950X (16-Core) | NVIDIA GeForce RTX 3080 | 32GB | Windows 10 | |
|
||||
| [Howard Trickey](https://projects.blender.org/howardt) | Apple M3 Max (16-Core) | Apple M3 Max | 64GB | macOS Sonoma 14.5 | |
|
||||
|
||||
@ -110,7 +110,7 @@ sudo yum install -y hip-devel rocm-llvm rocm-core rocm-device-libs5.7.3.x86_64
|
||||
|
||||
### Windows
|
||||
|
||||
Install the [HIP SDK](https://www.amd.com/en/developer/rocm-hub/hip-sdk.html) for
|
||||
Install the [HIP SDK](https://www.amd.com/en/developer/resources/rocm-hub/hip-sdk.html) for
|
||||
windows. By default the installer creates the environment variable
|
||||
`HIP_PATH` which is used in cmake for locating the SDK location.
|
||||
|
||||
|
||||
@ -397,4 +397,30 @@ instructions on using VSCode for Blender development.
|
||||
> ```
|
||||
|
||||
>? NOTE: **Git Integration**
|
||||
> TODO
|
||||
> To have VSCode navigate to the Blender repository from context menus, first install
|
||||
> the following:
|
||||
>
|
||||
> - **Git Lens** (`eamodio.gitlens`)
|
||||
>
|
||||
> Add the following to your user `settings.json`
|
||||
>
|
||||
> ```json
|
||||
> ...
|
||||
> "gitlens.remotes": [{
|
||||
> "domain": "projects.blender.org",
|
||||
> "type": "Custom",
|
||||
> "name": "Blender",
|
||||
> "protocol": "https",
|
||||
> "urls": {
|
||||
> "repository": "https://projects.blender.org/${repo}",
|
||||
> "branches": "https://projects.blender.org/${repo}/branches",
|
||||
> "branch": "https://projects.blender.org/${repo}/commits/${branch}",
|
||||
> "commit": "https://projects.blender.org/${repo}/commit/${id}",
|
||||
> "file": "https://projects.blender.org/${repo}/src/{file}${line}",
|
||||
> "fileInBranch": "https://projects.blender.org/${repo}/src/${branch}/${file}${line}",
|
||||
> "fileInCommit": "https://projects.blender.org/${repo}/srs/commit/${id}/${file}${line}",
|
||||
> "fileLine": "#L${line}",
|
||||
> "fileRange": "#L${start}-L${end}"
|
||||
> }
|
||||
> }]
|
||||
> ```
|
||||
@ -28,9 +28,9 @@ There are some over-arching conventions for Blenders code base.
|
||||
|
||||
- Use descriptive names for global variables and functions.
|
||||
- Naming should follow the `snake_case` convention.
|
||||
- Public function names should include capitalized module identifier,
|
||||
object and property they're operating and operation itself. Very
|
||||
familiar with RNA callbacks names: `BKE_object_foo_get(...)` /
|
||||
- Public function names should include the module identifier in all
|
||||
capitals, object and property they're operating and operation itself.
|
||||
Very familiar with RNA callbacks names: `BKE_object_foo_get(...)` /
|
||||
`BKE_object_foo_set(...)`:
|
||||
``` c
|
||||
/* Don't: */
|
||||
@ -49,11 +49,53 @@ There are some over-arching conventions for Blenders code base.
|
||||
```
|
||||
- Local variables should be short and to the point.
|
||||
|
||||
### Size, Length & Count
|
||||
|
||||
Variables and struct and class members representing size, length or count should use the following suffixes:
|
||||
|
||||
- `_num`: The number of items in an array, vector or other container.
|
||||
- `_count`: Accumulated, counted values (such as the number of items in a linked-list).
|
||||
- `_size`: Size in bytes.
|
||||
- `_len`: For strings (the length of the string without it's null byte, as used in `strlen`).
|
||||
|
||||
For example:
|
||||
``` Cpp
|
||||
/* Struct members. */
|
||||
struct {
|
||||
/* An allocated C array of integers. */
|
||||
int *lut;
|
||||
/* The number of elements in the `lut` array. */
|
||||
int lut_num;
|
||||
/* The allocated size of the `lut` pointer, in bytes. */
|
||||
size_t lut_size;
|
||||
}
|
||||
|
||||
/* Function arguments. */
|
||||
void function(int *lut, int lut_num);
|
||||
```
|
||||
|
||||
Use the same suffixes for functions and methods returning that type of data,
|
||||
with one exception for generic C++ containers: the standard library and our
|
||||
own `blender::` BLI library use a `size()` method to return their number of items.
|
||||
|
||||
For example:
|
||||
``` Cpp
|
||||
int BLI_listbase_count(const ListBase *list);
|
||||
int BLI_ghash_num(ghash);
|
||||
int BLI_dynstr_len(ds);
|
||||
|
||||
/* But for C++ generic containers: */
|
||||
/**
|
||||
* Return how many values are currently stored in the vector.
|
||||
*/
|
||||
int64_t size() const {...}
|
||||
```
|
||||
|
||||
### Macros, Enums, Inline functions
|
||||
|
||||
- Names of macros defining constants and labels in enums should be
|
||||
capitalized.
|
||||
- Macro names should be capitalized.
|
||||
in all capitals.
|
||||
- Macro names should be in all capitals.
|
||||
- Enums used in DNA files should have explicit values assigned.
|
||||
|
||||
### Function arguments
|
||||
|
||||
28
docs/handbook/guidelines/design/a4_design.md
Normal file
28
docs/handbook/guidelines/design/a4_design.md
Normal file
@ -0,0 +1,28 @@
|
||||
# A4 Design
|
||||
|
||||
Inspired by Toyota A3 process, the idea is to synthetize all the information relevant to a design proposal in a piece of A4 (or 1920x1080).
|
||||
|
||||
* This prevents a more extensive presentation (e.g., slideshow) to get derailed because of small details.
|
||||
* A good strategy is to organize the different sections in context, from the big picture to specific details.
|
||||
|
||||
## Examples
|
||||
|
||||
Those are a few examples of design documents that were presented to Ton Roosendaal between 2021 and 2022.
|
||||
|
||||
### Spreadsheet Editor
|
||||
|
||||
Implemented in 2.93 LTS.
|
||||
|
||||
{style="width:800px;"}
|
||||
|
||||
### Asset Bundle
|
||||
|
||||
Proposal, for Blender 3.0.
|
||||
|
||||
{style="width:800px;"}
|
||||
|
||||
### Hair
|
||||
|
||||
Incomplete A4 Design, in the end the information was better presented as a more complete [blog post](https://code.blender.org/2022/07/the-future-of-hair-grooming/).
|
||||
|
||||
{style="width:800px;"}
|
||||
@ -0,0 +1,13 @@
|
||||
# Communication and Presentation
|
||||
|
||||
## Communication
|
||||
|
||||
* Feedback thread
|
||||
* Blog posts
|
||||
|
||||
## Presentation
|
||||
|
||||
* Diagramas
|
||||
* Wireframes
|
||||
* High-fidelity mockups
|
||||
* [A4](a4_design.md)
|
||||
35
docs/handbook/guidelines/design/decision_tree.md
Normal file
35
docs/handbook/guidelines/design/decision_tree.md
Normal file
@ -0,0 +1,35 @@
|
||||
# Decision Tree
|
||||
|
||||
What to consider when proposing (or analyzing) a design?
|
||||
|
||||
Example of questions:
|
||||
|
||||
* Which problem is this trying to solve?
|
||||
* Who is this solving for? (what is the target audience: beginners? Experienced users? Animators? Riggers?)
|
||||
* Within the context of Blender as a multi-purpose DCC, how does this feature fit on it?
|
||||
* Which areas of Blender are affected by this design?
|
||||
* What is the impact on existing workflows?
|
||||
* How does it impact the other user-groups and workflows in Blender?
|
||||
* Which new problems do this introduce?
|
||||
|
||||
## Bottom-Up
|
||||
|
||||
Sometimes the decision tree is a bottom-up process, where the different questions can cascade up to different levels.
|
||||
|
||||
Take this example: “I want to add a new Bake button on the viewport header”.
|
||||
|
||||
On a surface level you need to see how this affects the real-state of the header, which workflow you are prioritizing with this change, and what may need to be reshuffled.
|
||||
|
||||
|
||||
On a second level you can look at whether Blender has other similar buttons. In this case you can quickly see that there are no tools (operators) called directly from the header.
|
||||
|
||||
On a third intermediate level you could see how this affects other editors. If we have Baking on the viewport, should we have this also for the animation editor? The Image Editor?
|
||||
|
||||
On a higher level you need to understand what will this new button bring to the workflow, what is the problem leading to this solution, and whether there are other solutions that may be more suitable.
|
||||
|
||||
Similar examples: “Should we have buttons in the Properties Editor?”, “Should we have buttons on nodes?”
|
||||
|
||||
## Top-Down
|
||||
|
||||
The opposite can also happen and the initial concept is a high-level concept. It is also important to know how it impacts the other areas of Blender, how the concept cascades down to the workflows, editors and ultimately the UI/UX.
|
||||
|
||||
39
docs/handbook/guidelines/design/examples/assets.md
Normal file
39
docs/handbook/guidelines/design/examples/assets.md
Normal file
@ -0,0 +1,39 @@
|
||||
# Assets
|
||||
|
||||
First read the [2020 blog post](https://code.blender.org/2020/03/asset-manager/) to see the complete asset manager design proposal. Here you can find a breakdown explanation of how this proposal came to be.
|
||||
|
||||
## Design
|
||||
|
||||
At the core of this project, the design was defined as a single line: *"An asset is a data-block with meaning"*.
|
||||
|
||||
On top of this big-picture design, it was also proposed that users should be in control of managing the assets (this was partily re-visited much later though). These constrains lead to a few implications:
|
||||
|
||||
* Users don't create an asset
|
||||
* Instead they can set an existing data-block as an asset by adding meaning (meta-data) to it.
|
||||
* Users manage assets the same way they manage data-blocks
|
||||
* Assets can rely on linked data-blocks.
|
||||
* Assets can package all its depedencies.
|
||||
* A .blend file can contain multiple assets.
|
||||
|
||||
## Visualization
|
||||
|
||||
|
||||
|
||||
This visualization builds on top of the [View Layer](https://code.blender.org/2017/09/view-layers-and-collections/) design.
|
||||
It tries to create a mental model of how assets are interwined inside the main Blender data-base.
|
||||
|
||||
The following tries to make it clear that there is little difference between a regular data-block and an asset:
|
||||
{style="background-color:#1f2129"}
|
||||
|
||||
## Life cycle of an asset
|
||||
|
||||
[“Create, edit, share and use it.”](https://code.blender.org/2020/03/asset-manager/#life-cycle-of-an-asset)
|
||||
|
||||
During the design phase User Story Mapping was used to understand what are the possible actions a user may do with an asset, and ways to group them:
|
||||
|
||||
* Create
|
||||
* Edit
|
||||
* Share
|
||||
* Use
|
||||
|
||||
Having these clear defined group of actions helped to make sure any feature which was discussed was understood within one of these context. It also helped the user interface organization, where the separation between the group of actions were desired.
|
||||
64
docs/handbook/guidelines/design/examples/camera_lens.md
Normal file
64
docs/handbook/guidelines/design/examples/camera_lens.md
Normal file
@ -0,0 +1,64 @@
|
||||
# Camera Lens
|
||||
|
||||
## Introduction
|
||||
|
||||
VFX professionals need to map real camera footage with VFX rendered effects.
|
||||
Let's look at a recent request from people to implement something like [Lentil](http://www.lentil.xyz/) in Blender.
|
||||
|
||||
This is not a new problem, and over the years this topic has been brought up a few times.
|
||||
|
||||
## Solution space
|
||||
|
||||
Over the years there have been different proposed solutions:
|
||||
|
||||
* Camera nodes
|
||||
* Distortion lookup table
|
||||
* Lens parametrization
|
||||
|
||||
While distortion lookup was eventuallt [implemented on the Blender Game Engine](https://paulbourke.net/dome/BlenderiDome/),
|
||||
the most popular influx of proposals was on parametrization:
|
||||
|
||||
* *2011*: [Cycles panorama camera - custom lens mapping](https://projects.blender.org/blender/blender/issues/35428)
|
||||
* *2014*: [Anamorphic (fake) Bokeh](https://code.blender.org/2014/08/anamorphic-bokeh/)
|
||||
* *2022*: [Lens Distortion Models](https://devtalk.blender.org/t/lens-distortion-models/25439)
|
||||
* *2024*: [Adding Fisheye624 camera projection model](https://projects.blender.org/blender/blender/pulls/124365)
|
||||
|
||||
|
||||
## Questions to be answered:
|
||||
|
||||
Let's try answering a few of the [decision tree](../decision_tree.md) example questions:
|
||||
|
||||
* *Which problem is this trying to solve?*
|
||||
* Replicating the effect of real cameras for 100% CGI shots, or mixed real-footage + VFX.
|
||||
* *Who is this solving for? (what is the target audience: beginners? Experienced users? Animators? Riggers?)*
|
||||
* VFX artists (in particular pre-viz artists), mid to experienced.
|
||||
* This is also to say that the audience is not researchers/academics.
|
||||
* *Within the context of Blender as a multi-purpose DCC, how does this feature fit on it?*
|
||||
* It connects to the existing VFX user group.
|
||||
* *Which areas of Blender are affected by this design?*
|
||||
* Rendering, but also compositing and tracking should be taken into consideration.
|
||||
* *What is the impact on existing workflows?*
|
||||
* Not relevant, the feature is isolated.
|
||||
* *How does it impact the other user-groups and workflows in Blender?*
|
||||
* There is an overlap with VR research (see Fisheye624) in the sense that it is another user group which may fight for the standard to be adopted.
|
||||
* *Which new problems do this introduce?*
|
||||
* This aggravates the feature disparity between Cycles and EEVEE.
|
||||
* In render mode: This doesn't play well with grease-pencil, modelling or even selection.
|
||||
* Technically these are not new problems, since they exist already for panorama and fisheye lens.
|
||||
* Supporting arbitrary parametrization may be a slippery slope to support (and keep maintaining) multiple incompatible systems.
|
||||
|
||||
## Follow ups
|
||||
|
||||
This is an open-ended problem at the moment, so there is no example of a final design.
|
||||
|
||||
That said any design which tries to tackle this should present a solution for:
|
||||
|
||||
* How does it relate to motion tracking?
|
||||
* Can the distortion models be consistent?
|
||||
* How to eventually support this with EEVEE, if possible (and if not possible explain why).
|
||||
* How to communicate in the viewport that the current rendering more is not compatible with the overlay draw engine.
|
||||
* And what to do about it? Disable the draw engine in these cases? Draw it mismatching the render engine buffer?
|
||||
* How universal these parameters are, who is adopting them already?
|
||||
* What are the known alternatives of parametrization?
|
||||
* Is this model future-compatible with a camera-nodes solution? (can they be converted in either direction)?
|
||||
* Which usergroup to prioritize (and which to frustate), and why.
|
||||
128
docs/handbook/guidelines/design/examples/geometry_nodes.md
Normal file
128
docs/handbook/guidelines/design/examples/geometry_nodes.md
Normal file
@ -0,0 +1,128 @@
|
||||
# Geometry Nodes
|
||||
|
||||
Geometry Nodes was a project which started officially on October 19th, 2020.
|
||||
This document covers its design process and dynamics, with emphasis on when this was still a project before moving to module work.
|
||||
|
||||
Topics:
|
||||
|
||||
* [Journey](#journey)
|
||||
* [Caveat](#caveat)
|
||||
* [Team](#team)
|
||||
* [Dynamic](#dynamic)
|
||||
* [Product ownership](#product-ownership)
|
||||
* [Links](#links)
|
||||
* [Design presentations](#design-presentations)
|
||||
* [Design proposals](#design-proposals)
|
||||
* [Workshop and posts with design snippets](#workshop-and-posts-with-design-snippets)
|
||||
|
||||
## Journey
|
||||
|
||||
These steps roughly represent the order on which the design and development process was carried out.
|
||||
|
||||
* **Audience**
|
||||
* The project started by picking real artists (as oppose to personas) and connecting to them.
|
||||
* Andy Goralczyk (art director / lead VFX).
|
||||
* **Discovery**
|
||||
* Evaluated what was already possible or planned for the ongoing particle-nodes project.
|
||||
* Comb over previous open movie projects, which ones would benefit from a new particle system.
|
||||
* Interview with Andy: Present him all the possibilities, get back that all he was really looking for were good, predictable set dressing tools.
|
||||
* **Scope**
|
||||
* Decision to pivot to set dressing.
|
||||
* Analyze upcoming movie project (Sprite Fright) to see which shots could benefit from Geometry Nodes.
|
||||
* List these as potential use-cases.
|
||||
* **Design**
|
||||
* Discussion with stakeholders to agree on design as well as implementation approach.
|
||||
* At this point, the concept of "Geometry Nodes" as a modifier was consolidated.
|
||||
* **Planning**
|
||||
* Come up with use cases that make sense in terms of incremental complexity.
|
||||
* Dissect the initial use cases - how to make them? Which nodes are required.
|
||||
* Build real production files in preparation for the first use-case.
|
||||
* **Prototyping**
|
||||
* This project was a little different since there were a lot of technical solutions already implemented under the hood (due to the prior particle-nodes experiments).
|
||||
* If that was not the case, it would have been reasonable to first do a prototype for the simplest use cases before building at scale.
|
||||
* Nonetheless, the initial deliverables could have been considered spikes (development to learn, to be trashed) - more on that in validation.
|
||||
* As a rule of thumb, you want to get unknowns out of the way, and in Blender, this is often new design, big intended performance gains, or depending/navigating old code (technical debt).
|
||||
* **Validation**
|
||||
* Before proceeding, the design should have been more widely presented (to stakeholders - design leads) before continuing.
|
||||
* This would allow iteration over the ideas, to see if the intended outcomes were more concrete.
|
||||
* Although things were presented and approved to continue to the next milestones, there was a blind spot when it came to the so-called level of abstraction the system should have supported from the get-go ([*](#caveat)).
|
||||
* **Delivery**
|
||||
* The project was designed to be releasable at every step of the way.
|
||||
* This is deeply rooted in Blender's motto of: release value often, document what works, document what is not targeted yet.
|
||||
* For Geometry Nodes, this meant that the moment only a few nodes were in (enough to scatter some pebbles), the system was considered ready for a release - even if it meant it couldn't yet do plenty of other use cases.
|
||||
|
||||
## Caveat
|
||||
|
||||
For a more accurate account of events, watch the [2022 Blender Conference presentation](https://www.youtube.com/watch?v=nmGs9fEPcrA&list=PLa1F2ddGya__2Ip2UB-xp6M54cQVvw1W-) and how the team had to backtrack on the attributes design.
|
||||
|
||||
Basically, the expectation was that hard-coded values should not have been supported as the primary way to access attributes. Instead, geometry nodes systems should be fully encapsulatable, with all its dependencies coming from "outside". This was only course-corrected after two Blender releases leading to a cost (no-backward compatibility, outdated documentation, community trust).
|
||||
|
||||
This led to what became the Fields design, not without great breakage. Some of this could have been avoided had the PM made sure the stakeholders
|
||||
were actually aware of what was being built - e.g., present in some of the product demos.
|
||||
|
||||
---
|
||||
|
||||
Since the topic at hand is design, it is important to also acknowledge how the design competence will be fulfilled by the team.
|
||||
|
||||
## Team
|
||||
|
||||
This was a project that was known to require a lot of design work. So design was accounted for when structuring the team.
|
||||
At the core of it, the following roles were filled:
|
||||
|
||||
* **Lead developer**: Architecture and mentoring.
|
||||
* **Junior developer**: Ensure the continuity of the project, and the overall readability of the code.
|
||||
* **Designer features**: Tool designer (which nodes are required, which features are needed) and demo files.
|
||||
* **Designer UI**: Everything from names to shapes to colors.
|
||||
* **Product manager**: Worked as Product Owner, but basically: scope, prioritization, communication, sign-off with stakeholders.
|
||||
* **Scrum master**: Process (the team took that as an opportunity to try scrum as well).
|
||||
|
||||
In this setup, the UX was a joint effort between everyone. Some of the big picture design (e.g., Geometry Nodes are modifiers, full encapsulation, ... came from stakeholders aka the CEO).
|
||||
|
||||
At times there were more developers involved, but always aligned with this core structure.
|
||||
|
||||
### Dynamic
|
||||
|
||||
* **Developers**: Having more than one developer made sure the code was reviewed internally and all decisions were checked by someone else.
|
||||
* **Technical artist**: Having the ultimate target audience in the team made sure all the designs were anchored on production needs and validated off the gate.
|
||||
* **UI designer**: Having a centralized person to make opinionated decisions helps to give the project coherence (and personality).
|
||||
* **Product manager**: In this case, the PM worked a lot as a bridge between the stakeholders and the team, avoiding surprises to both ([*](#caveat)) and building the trust to give the team more autonomy.
|
||||
* **Scrum master**: Although the project moved on from scrum, it helped a lot to be forced into a framework which guaranteed a lot of shared context, syncing and overall communication and collaboration. At the core of it was a shared responsibility for all the tasks and understanding their dependencies, making sure they were clear to everyone. This framework is particularly handy for important epics which required hairy design discussions so easily postponed.
|
||||
|
||||
### Product ownership
|
||||
|
||||
Although the roles were distinct, product ownership was everyone's responsibility. In practice, it means:
|
||||
|
||||
* No one was too good to work on a task (doesn't matter if it is testing features or writing documentation).
|
||||
* Any problem the project had was everyone's problem - no room for doing your part and being happy about it if the whole wasn't working.
|
||||
* Part of this sense of ownership came from understanding that the outcome is more than the sum of the parts (outputs).
|
||||
|
||||
## Links
|
||||
|
||||
### Design presentations
|
||||
|
||||
* [Initial Design](https://devtalk.blender.org/t/2020-09-03-particle-workshop/15172)
|
||||
* [Attributes and Fields](https://code.blender.org/2021/08/attributes-and-fields/)
|
||||
* [Hair](https://code.blender.org/2022/07/the-future-of-hair-grooming/)
|
||||
|
||||
### Design proposals
|
||||
|
||||
* [Fields and Anonymous Attributes](https://devtalk.blender.org/t/fields-and-anonymous-attributes-proposal/19450) - June 2021
|
||||
* [Expandable Geometry Socket](https://devtalk.blender.org/t/expandable-geometry-socket-proposal/19604) - July 2021
|
||||
* [Attribute Socket Types](https://devtalk.blender.org/t/proposal-for-attribute-socket-types/19177) - June 2021
|
||||
* [Enum Sockets](https://devtalk.blender.org/t/enum-sockets-proposal/21318) - November 2021
|
||||
* [Anonymous Attributes, Attribute Sockets and Node Group Processors](https://devtalk.blender.org/t/anonymous-attributes-attribute-sockets-and-node-group-processors-proposal/19673) - July 2021
|
||||
* [Shareable Named Attribute Node](https://devtalk.blender.org/t/shareable-named-attribute-node-proposal/20386) - September 2021
|
||||
* [Explicit Instancing](https://devtalk.blender.org/t/explicit-instancing-proposal/20494) - September 2021
|
||||
* [Fields and Anonymous Attributes](https://devtalk.blender.org/t/fields-and-anonymous-attributes-proposal/19450) - June 2021
|
||||
* [Volumes in Geometry Nodes](https://devtalk.blender.org/t/volumes-in-geometry-nodes-proposal/31917) - November 2023
|
||||
|
||||
### Workshop and posts with design snippets
|
||||
|
||||
* [Nodes Modifier Part I: Sprites](https://code.blender.org/2020/11/nodes-modifier-part-i-sprites/)
|
||||
* [Everything Nodes and the Scattered Stone](https://code.blender.org/2020/12/everything-nodes-and-the-scattered-stone/)
|
||||
* [Geometry Nodes and the Melting Iceberg](https://code.blender.org/2021/02/geometry-nodes-and-the-melting-iceberg/)
|
||||
* [Nodes Workshop – June 2021](https://code.blender.org/2021/07/nodes-workshop-june-2021/)
|
||||
* [Geometry Nodes Icon](https://code.blender.org/2022/05/geometry-nodes-icon/)
|
||||
* [Node Tools Interface and Baking](https://code.blender.org/2023/06/node-tools-interface-and-baking/)
|
||||
* [Node Tools](https://code.blender.org/2023/10/node-tools/)
|
||||
* [Geometry Nodes Workshop: November 2023](https://code.blender.org/2023/11/geometry-nodes-workshop-november-2023/)
|
||||
15
docs/handbook/guidelines/design/examples/index.md
Normal file
15
docs/handbook/guidelines/design/examples/index.md
Normal file
@ -0,0 +1,15 @@
|
||||
# Examples
|
||||
|
||||
* [Assets](assets.md)
|
||||
|
||||
---
|
||||
|
||||
## Additional Design Applications
|
||||
|
||||
Answering some [fundamental questions](../decision_tree.md) to better frame the problem:
|
||||
|
||||
* [Camera Lens](camera_lens.md)
|
||||
|
||||
Systematic view of a project, and how design is intertwined:
|
||||
|
||||
* [Geometry Nodes](geometry_nodes.md)
|
||||
33
docs/handbook/guidelines/design/ideas_concept.md
Normal file
33
docs/handbook/guidelines/design/ideas_concept.md
Normal file
@ -0,0 +1,33 @@
|
||||
# Idea, Concept, Design
|
||||
|
||||
It is important to be able to tell an idea, a concept and a design apart. They are to be treated differently and to be consulted on different stages of development.
|
||||
|
||||
## Ideas
|
||||
|
||||
A solution-driven suggestion, which can be used to find important problems to tackle.
|
||||
|
||||
Even when the specific solution may be up for debate, it can still help to show the feasibility of having a solution to the problem, as well as its scope and cost.
|
||||
|
||||
The more the problem is framed, a big picture is presented and different scenarios are considered, the more an idea gets closer to being a design.
|
||||
|
||||
See [rightclickselect.com](https://rightclickselect.com/) to see examples of Blender ideas.
|
||||
|
||||
## Concept
|
||||
|
||||
A visual mockup of how a design could look like.
|
||||
|
||||
To be referenced on the final stages of design, when there is a design in place and it is time to see how things should look like.
|
||||
|
||||
When concepts are not following a proposed design, they are basically a visualization of an idea and should be treated like any other ideas.
|
||||
|
||||
Concepts early in the design stage are useful to show that there are feasible solutions, and the project won’t hit a dead-end down the line.
|
||||
|
||||
Fleshed out concepts are particularly important after a design is already in place. To explore UI variations for prototypes and the final solution.
|
||||
|
||||
## Design
|
||||
|
||||
A comprehensive document highlighting the big picture, the problem it tries to solve, its target audience, how it impacts all aspects of Blender, how it affects other user groups, and proposed solutions.
|
||||
|
||||
Solutions should be framed from the outcome point of view. And you should be able to connect the solution with its intended outcome (e.g., “once Bone Collections are implemented, riggers will be able to organize their rigs better by putting control bones and deform bone in separate collections”).
|
||||
|
||||
While the discussion eventually is centered around the proposed solution, there needs to be first agreement on all the other aspects. This is where a lot of times we jump the gun and discuss different solutions to the problem, before even considering whether this is the correct problem we should tackle.
|
||||
14
docs/handbook/guidelines/design/index.md
Normal file
14
docs/handbook/guidelines/design/index.md
Normal file
@ -0,0 +1,14 @@
|
||||
# Design Proposals
|
||||
|
||||
"Design isn't a product that designers produce, design is a process that designers facilitate." --Leah Buley
|
||||
|
||||
This is intended for everyone involved in the Blender development process, regardless of whether they are contributors, modules or staff members.
|
||||
|
||||
This aims at helping the modules to handle better the contribution from the community and present and forward with its own design proposals.
|
||||
|
||||
Topics:
|
||||
|
||||
* [Decision Tree](decision_tree.md)
|
||||
* [Idea, Concept, Design](ideas_concept.md)
|
||||
* [Communication and Presentation](communication_presentation.md)
|
||||
* [Examples](examples/index.md)
|
||||
4
docs/handbook/guidelines/design/navigation.md
Normal file
4
docs/handbook/guidelines/design/navigation.md
Normal file
@ -0,0 +1,4 @@
|
||||
- [Decision Tree](decision_tree.md)
|
||||
- [Idea, Concept, Design](ideas_concept.md)
|
||||
- [Communication and Presentation](communication_presentation.md)
|
||||
- [Examples](examples/index.md)
|
||||
128
docs/handbook/guidelines/hosted_extensions.md
Normal file
128
docs/handbook/guidelines/hosted_extensions.md
Normal file
@ -0,0 +1,128 @@
|
||||
# Extensions officially hosted on blender.org
|
||||
|
||||
The general recommendation is for
|
||||
[Extensions](https://docs.blender.org/manual/en/dev/extensions/index.html) to be hosted on personal
|
||||
repositories on [projects.blender.org](https://projects.blender.org) or external host services.
|
||||
|
||||
In some cases, however, these extensions can be hosted on official `blender.org` repositories:
|
||||
|
||||
* Extensions which are mostly maintained by Blender developers.
|
||||
* Extensions which are popular but have no active maintainer at the moment
|
||||
(e.g., some of the add-ons bundled with Blender until the version 4.1).
|
||||
|
||||
All of those extensions will be hosted on
|
||||
[projects.blender.org/extensions](https://projects.blender.org/extensions/).
|
||||
Each extension should have its own repository and issue tracker.
|
||||
|
||||
# Create a new repository
|
||||
|
||||
* Create a new repository on
|
||||
[projects.blender.org/extensions](https://projects.blender.org/extensions/).
|
||||
* It is recommended for the repository to have the `main` branch protected, with "Enable Push".
|
||||
* The add-on maintainers need to be added as Collaborators for the repository.
|
||||
|
||||
|
||||
# Migrate from the add-ons repository
|
||||
|
||||
In some cases add-ons need to be extracted from a repository
|
||||
where other add-ons were also developed.
|
||||
The following steps show how to do so while preserving the git log history.
|
||||
|
||||
## Get a fresh copy of the add-ons
|
||||
|
||||
```sh
|
||||
git clone https://projects.blender.org/blender/blender-addons.git
|
||||
cd blender-addons
|
||||
```
|
||||
|
||||
!!! Warning
|
||||
Some of the commands here may ruin your existing repository.
|
||||
Work with a new copy of the repository to avoid any troubles.
|
||||
|
||||
## Create a new branch only with the folder you want
|
||||
|
||||
The command is:
|
||||
```sh
|
||||
git subtree split -P <source_folder> -b <target_branch>
|
||||
```
|
||||
|
||||
Let's for example create a new repository for the `io_shape_mdd` add-on.
|
||||
|
||||
```sh
|
||||
git subtree split -P io_shape_mdd -b io_shape_mdd_new
|
||||
```
|
||||
|
||||
In this example it will copy:
|
||||
```
|
||||
./io_shape_md/
|
||||
├─ __init__.py
|
||||
├─ export_mdd.py
|
||||
└─ import_mdd.py
|
||||
```
|
||||
|
||||
Into:
|
||||
```
|
||||
./__init__.py
|
||||
./export_mdd.py
|
||||
./import_mdd.py
|
||||
```
|
||||
|
||||
The new branch (io_shape_mdd_new) will have its original git history preserved.
|
||||
|
||||
|
||||
!!! Extra
|
||||
If you want to keep the files under the same subfolder,
|
||||
use [git filter-repo](https://github.com/newren/git-filter-repo) instead:
|
||||
```
|
||||
git checkout -b io_shape_mdd_new
|
||||
git filter-repo --path io_shape_mdd
|
||||
```
|
||||
|
||||
## Single file add-ons
|
||||
|
||||
For add-ons that only contain a single file you need to use
|
||||
[git filter-repo](https://github.com/newren/git-filter-repo).
|
||||
|
||||
```
|
||||
git checkout -b depsgraph
|
||||
git filter-repo --path-rename depsgraph_debug.py:__init__.py
|
||||
```
|
||||
|
||||
This will create a new branch (depsgraph) with a single `__init__.py` file,
|
||||
containing all the git history from the original file (depsgraph_debug.py).
|
||||
Extension add-ons always require a `__init__.py`.
|
||||
|
||||
Alternatively you can just get the file:
|
||||
|
||||
```
|
||||
git checkout -b depsgraph
|
||||
git filter-repo --path depsgraph_debug.py
|
||||
```
|
||||
|
||||
And create a `__init__.py` file later to load your extension.
|
||||
That's beyond the scope of this guide though.
|
||||
|
||||
## Push the repository online:
|
||||
|
||||
First you need to make sure you have access to the repository.
|
||||
|
||||
```
|
||||
git remote add io_shape_mdd.git git@projects.blender.org:extensions/io_shape_mdd.git
|
||||
git push -u io_shape_mdd.git io_shape_mdd_new:main
|
||||
```
|
||||
|
||||
# Publishing extensions
|
||||
|
||||
Now that the `.git` history is clear and the extension can be developed further,
|
||||
you can start making an extension.
|
||||
To convert an add-on into an extension follow
|
||||
[those steps](https://docs.blender.org/manual/en/dev/extensions/addons.html#converting-a-legacy-add-on-into-an-extension).
|
||||
|
||||
## Upload the extension
|
||||
|
||||
Upload the extension to [extensions.blender.org](https://extensions.blender.org/). If you need multiple contributors
|
||||
to co-maintain the extension on the platform please contact a moderator on
|
||||
[#extensions-moderators](https://blender.chat/channel/extensions-moderators).
|
||||
|
||||
After you upload the extension, remember to use the repository own issue tracker as the support
|
||||
URL on the [Extensions Platform website](https://extensions.blender.org/).
|
||||
@ -21,6 +21,8 @@ activities.
|
||||
|
||||
## Process
|
||||
|
||||
- [Design Proposals](design/index.md)
|
||||
- [New Committers](new_committers.md)
|
||||
- [Reverting Commits](revert_a_commit.md)
|
||||
- [Code Quality Day](code_quality_day.md)
|
||||
- [Extensions Hosted on blender.org](hosted_extensions.md)
|
||||
@ -6,3 +6,4 @@
|
||||
- [Release Notes Guide](release_notes.md)
|
||||
- [License Headers](license_headers.md)
|
||||
- *
|
||||
- [Extensions on blender.org](hosted_extensions.md)
|
||||
|
||||
@ -40,10 +40,10 @@ Here's the standard checklist & guidelines all new devs need to read:
|
||||
6. Document new features and changes in the [release notes](../../release_notes/index.md),
|
||||
either before or directly after committing a feature. Please follow [the guidelines](https://developer.blender.org/docs/handbook/guidelines/release_notes/).
|
||||
|
||||
7. Blender has stages in its development cycle called BCon levels.
|
||||
7. Blender has phases in its development cycle.
|
||||
Patches may be delayed or refused (even if the patch is acceptable)
|
||||
if a new Blender version is being prepared for release. To avoid
|
||||
this, make sure to check on the current BCon stage. See the
|
||||
this, make sure to check on the current release phase. See the
|
||||
[Release Cycle](../release_process/release_cycle.md) docs.
|
||||
|
||||
## Best Practice
|
||||
|
||||
@ -43,7 +43,7 @@ page on blender.org.
|
||||
- Some info / instructions regarding the scene, comprehensible for novice Blender users.
|
||||
- The Creative Commons license type: CC-0 (preferred), CC-BY or CC-BY-ND.
|
||||
- Your name or nickname.
|
||||
- A URL (e.g. your portfolio or Twitter profile URL).
|
||||
- A URL (e.g. your portfolio or social media URL).
|
||||
|
||||
- Optionally, you may choose to add a specific info text to different
|
||||
workspaces, to explain more of your creative process (see example
|
||||
|
||||
@ -58,11 +58,11 @@ These names can then be used to search through the code.
|
||||
|
||||
Short:
|
||||
|
||||
- [Campbell's Tips for Code Navigation](https://www.youtube.com/watch?v=_kniMTbcCko&t=38s)
|
||||
- [Campbell's Tips for Code Navigation](https://www.youtube.com/watch?v=_kniMTbcCko)
|
||||
- [Campbell's Code Navigation and Code Fix](https://www.youtube.com/watch?v=5Ymoav0nNWQ)
|
||||
|
||||
Longer:
|
||||
|
||||
- [Dalai's Code Dive Video](https://www.youtube.com/watch?v=tCdx7gzp0Ac)
|
||||
- [Dalai's Bug Fix](https://www.youtube.com/watch?v=tQzKjf2_Hmk&t=157s)
|
||||
- [Dalai's Bug Fix](https://www.youtube.com/watch?v=tQzKjf2_Hmk)
|
||||
|
||||
|
||||
@ -50,9 +50,9 @@ consult with admins and go to them for support.
|
||||
|
||||
**Admins**:
|
||||
[Bastien Montagne](https://projects.blender.org/mont29),
|
||||
[Brecht Van Lommel](https://projects.blender.org/brecht),
|
||||
[Campbell Barton](https://projects.blender.org/ideasman42),
|
||||
[Dalai Felinto](https://projects.blender.org/dfelinto),
|
||||
[Philipp Oeser](https://projects.blender.org/lichtwerk),
|
||||
[Sergey Sharybin](https://projects.blender.org/Sergey)
|
||||
|
||||
### Responsibilities
|
||||
|
||||
@ -19,19 +19,6 @@ these platforms is normally only done by platform maintainers.
|
||||
For Linux, precompiled libraries must be downloaded once manually as per
|
||||
the build instructions, and can then be updated with `make update`.
|
||||
|
||||
## System Packages
|
||||
|
||||
On Linux, the system package manager can also be used to install many
|
||||
dependencies. See the Linux build instructions for details.
|
||||
|
||||
The resulting builds will not be portable, but libraries can be shared
|
||||
with other software on the system.
|
||||
|
||||
The simplest way to install all needed packages is to run (from the
|
||||
blender source directory):
|
||||
|
||||
` build_files/build_environment/install_linux_packages.py --all`
|
||||
|
||||
## make deps
|
||||
|
||||
The Blender repository has a CMake based system to build all library
|
||||
@ -44,3 +31,16 @@ operating system installs. A successful build may require some manual
|
||||
configuration or edits to the code. Minimal instructions on how to use
|
||||
it can be found in
|
||||
[build_files/build_environment/CMakeLists.txt](https://projects.blender.org/blender/blender/src/branch/main/build_files/build_environment/CMakeLists.txt).
|
||||
|
||||
## System Packages
|
||||
|
||||
On Linux, the system package manager can also be used to install many
|
||||
dependencies. See the Linux build instructions for details.
|
||||
|
||||
The resulting builds will not be portable, but libraries can be shared
|
||||
with other software on the system.
|
||||
|
||||
The simplest way to install all needed packages is to run (from the
|
||||
blender source directory):
|
||||
|
||||
` build_files/build_environment/install_linux_packages.py --all`
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
## ARM
|
||||
|
||||
The basic thing to build libraries is to run `make deps`, which will
|
||||
download and compile all libraries in `../build_darwin/deps`.
|
||||
download and compile all libraries in `../build_darwin/deps_arm64`.
|
||||
|
||||
Most likely it will tell you that you are missing some tools, and give
|
||||
you homebrew commands to install them.
|
||||
@ -11,9 +11,9 @@ you homebrew commands to install them.
|
||||
After this is done it will automatically install the updated libraries
|
||||
to `lib/macos_arm64` from where they can be committed.
|
||||
|
||||
## x86\_64 Cross Compilation
|
||||
## x64 Cross Compilation
|
||||
|
||||
x86\_64 libraries are currently cross compiled on ARM, which is
|
||||
x64 libraries are currently cross compiled on ARM, which is
|
||||
convenient to have on a single machine.
|
||||
|
||||
### Homebrew
|
||||
@ -21,7 +21,12 @@ convenient to have on a single machine.
|
||||
This requires two homebrew installs, one for arm and one for x86\_64.
|
||||
They will be installed in different folders automatically.
|
||||
|
||||
macOS supports dropping into a x86\_64 terminal like this.
|
||||
Install Rosetta if you haven't already:
|
||||
``` bash
|
||||
/usr/sbin/softwareupdate --install-rosetta --agree-to-license
|
||||
```
|
||||
|
||||
macOS then supports dropping into a x86\_64 terminal like this.
|
||||
|
||||
``` bash
|
||||
arch -x86_64 zsh
|
||||
@ -41,7 +46,7 @@ else
|
||||
fi
|
||||
```
|
||||
|
||||
This probably replaces some existing code put there by homebrew.
|
||||
This probably replaces some existing code put there by Homebrew.
|
||||
|
||||
### Building
|
||||
|
||||
@ -51,12 +56,16 @@ Always drop into the x86\_64 terminal first.
|
||||
arch -x86_64 zsh
|
||||
```
|
||||
|
||||
Set up the build similar to this, modify paths as needed:
|
||||
With this, `make deps` will generate a build in `build_darwin/deps_x64`.
|
||||
|
||||
``` bash
|
||||
cmake -DHARVEST_TARGET=../blender/lib/macos_x64 -DCMAKE_OSX_ARCHITECTURES=x86_64 -S blender/build_files/build_environment -B build_darwin/deps_x64
|
||||
cd build_darwin/deps_x64
|
||||
make -j16 install
|
||||
## Validation
|
||||
|
||||
The libraries should be self contained, and only linking to macOS system libraries. And for example not anything in `/opt/homebrew`.
|
||||
|
||||
This can be checked as follows:
|
||||
```
|
||||
otool -L lib/macos*/**/*.dylib
|
||||
otool -L ../build_darwin/bin/Blender.app/Contents/MacOS/Blender
|
||||
```
|
||||
|
||||
## LTS and CVEs
|
||||
@ -77,6 +86,5 @@ rebuild correctly.
|
||||
* Consider installing Xcode by manually downloading it from the Apple developer site instead of the app store, to avoid unexpected automatic updates when the time is not convenient.
|
||||
* Command Line Tools currently don't work as OpenImageDenoise requires the Metal compiler tools that are only included with Xcode.
|
||||
* On macOS we do not use versioned library symlinks because Apple notarization rejects them for unknown reasons. The builds scripts automatically strip these and patch the dylibs to remove them.
|
||||
* MaterialX cmake config files have been tweaked to avoid using versioned symlinks. Changes to this folder should be reverted before committing. This should be fixed by patching this as part of the build, but it has not been done yet.
|
||||
* Before committing, be sure to run the tests as currently (without Git LFS) there is no convenient way to test things on the buildbot before landing. Use `make developer` and ensure test files are available, to be as close as possible to the buildbot.
|
||||
* Before committing big changes, push the libraries to a branch and make a PR with the corresponding hash. This way the libraries can be tested to work on the buildbot. For testing locally, use `make developer` and ensure test files are available, to be as close as possible to the buildbot.
|
||||
* There is some automatic rebuilding when dependencies of libraries change, but it does not account for everything. Often you may need to remove the `build` and `Release` folder to ensure things really rebuild, or particular folders contained in them if you know which specific ones need a rebuild.
|
||||
@ -1,23 +1,53 @@
|
||||
# Rocky Linux 8
|
||||
|
||||
The official Linux builds are done on Rocky Linux 8 . This makes
|
||||
it possible to have a portable build which will work on [VFX reference
|
||||
platform](https://vfxplatform.com/) compatible systems.
|
||||
The official Linux builds are done on Rocky Linux 8.
|
||||
This makes it possible to have a portable build which will work on
|
||||
[VFX reference platform](https://vfxplatform.com/) compatible systems.
|
||||
|
||||
This page describes how the official setup is created. This setup allows
|
||||
to compile Blender itself, as well as the Blender dependencies.
|
||||
|
||||
## Preparing the System
|
||||
|
||||
When provisioning a new system the following details may help:
|
||||
|
||||
**Disk Usage**
|
||||
|
||||
At the time of writing (Blender 4.2) disk usage is as follows:
|
||||
|
||||
- ~2.5 GB: Rocky8 installation.
|
||||
- ~34 GB: Packages installed by `linux_rocky8_setup.sh`.
|
||||
- ~42 GB: Blender's GIT repository & result of running `make deps`.
|
||||
- Some extra space for GIT LFS & building Blender is needed too.
|
||||
|
||||
Leaving some extra room to build Blender & run tests, a 100 GB is sufficient.
|
||||
|
||||
**System Memory**
|
||||
|
||||
The amount of memory needed to build packages depends on the number of simultaneous jobs,
|
||||
it is recommended no less than 16 GB of memory is used.
|
||||
|
||||
For building with 32 jobs requires about 64 GB of memory,
|
||||
although there are rough numbers to get an idea of what you may need.
|
||||
|
||||
**CPU Cores**
|
||||
|
||||
On Linux `make deps` builds dependencies one at a time with each build using all available cores.
|
||||
|
||||
In general the more cores available, the faster the build will complete.
|
||||
|
||||
|
||||
## Preparing Rocky 8 Environment
|
||||
|
||||
The release environment is based on the `Minimal Install` of the Rocky
|
||||
8. This document does not cover the steps needed to get the OS
|
||||
installed: it is rather straightforward and the default installation
|
||||
will get to where the systems needs to be.
|
||||
The release environment is based on the `Minimal Install` of the Rocky 8.
|
||||
This document does not cover the steps needed to get the OS installed:
|
||||
it is rather straightforward and the default installation will get to
|
||||
where the systems needs to be.
|
||||
|
||||
The
|
||||
[linux_rocky8_setup.sh](https://projects.blender.org/blender/blender/src/branch/main/build_files/build_environment/linux/linux_rocky8_setup.sh)
|
||||
script is then run as a root on the freshly installed system. It takes
|
||||
care of installing all dependencies.
|
||||
script is then run as a root on the freshly installed system.
|
||||
It takes care of installing all dependencies.
|
||||
|
||||
!!! Note
|
||||
Some system-wide changes are performed, so it is recommended to use a
|
||||
@ -25,20 +55,19 @@ care of installing all dependencies.
|
||||
|
||||
Congratulations, the base system is now ready!
|
||||
|
||||
Follow the [Building Cycles with GPU
|
||||
Binaries](../../building_blender/cycles_gpu_binaries.md) for the instructions
|
||||
related to installing the GPU compute toolkits.
|
||||
Follow the [Building Cycles with GPU Binaries](../../building_blender/cycles_gpu_binaries.md)
|
||||
for the instructions related to installing the GPU compute tool-kits.
|
||||
|
||||
## Building Blender
|
||||
|
||||
Blender is built from sources using the precompiled Rocky 8 libraries.
|
||||
Follow the Download Sources and Download Libraries sections from the
|
||||
[Linux Quick Setup](../../building_blender/linux.md).
|
||||
Note that all packages have already been installed, so that step from
|
||||
the Quick Setup should be skipped. Also make sure to get precompiled
|
||||
libraries for Rocky 8.
|
||||
Note that all packages have already been installed,
|
||||
so that step from the Quick Setup should be skipped.
|
||||
Also make sure to get pre-compiled libraries for Rocky 8.
|
||||
|
||||
The build is to be performed using gcc-11 toolchain. It is activated
|
||||
The build is to be performed using gcc-11 tool-chain. It is activated
|
||||
using the `scl` command:
|
||||
|
||||
``` bash
|
||||
|
||||
@ -19,7 +19,7 @@ severity 1 issues after the next stable release), on a fixed schedule
|
||||
|
||||
## Bug-fix flow diagram
|
||||
|
||||
Currently, at the beginning of bcon3, master is forked into a release
|
||||
Currently, at the beginning of Beta, master is forked into a release
|
||||
branch. Any bug fix relevant to the upcoming release happens in the
|
||||
release branch, and is merged to master.
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
## Overview
|
||||
|
||||
Towards the end of the [release cycle](release_cycle.md)
|
||||
a stabilizing branch is created. Below the `blender-v4.1-release`
|
||||
a stabilizing branch is created. Below the `blender-v4.2-release`
|
||||
branch is used as an example.
|
||||
|
||||
### Before a release
|
||||
@ -40,7 +40,7 @@ yourself!
|
||||
Develop the commit in a local branch based on the stabilizing branch:
|
||||
|
||||
```sh
|
||||
git checkout -b my-fix blender-v4.1-release
|
||||
git checkout -b my-fix blender-v4.2-release
|
||||
make update
|
||||
```
|
||||
|
||||
@ -51,7 +51,7 @@ commit (or remove) the local changes first.
|
||||
|
||||
Following the [pull request](../contributing/pull_requests.md) workflow,
|
||||
commit changes to your local branch, push to your fork and create a pull
|
||||
request. Choose `blender/blender-v4.1-release` as target instead of
|
||||
request. Choose `blender/blender-v4.2-release` as target instead of
|
||||
`blender/main`. Then merge the pull request as usual.
|
||||
|
||||
If you accidentally targeted `main`, you can change it following
|
||||
@ -64,11 +64,11 @@ If you accidentally targeted `main`, you can change it following
|
||||
the correct stabilizing branch and update to the latest changes.
|
||||
|
||||
```sh
|
||||
git checkout blender-v4.1-release
|
||||
git checkout blender-v4.2-release
|
||||
make update
|
||||
```
|
||||
|
||||
Once you have your local `blender-v4.1-release` up-to-date you can
|
||||
Once you have your local `blender-v4.2-release` up-to-date you can
|
||||
make your fix with the care you would do in normal `main` development.
|
||||
|
||||
Once done, necessary commits to fix have been made, and you’ve checked
|
||||
@ -79,7 +79,7 @@ If you accidentally targeted `main`, you can change it following
|
||||
### Merge to Main
|
||||
|
||||
As soon as you’ve successfully pushed your changes to
|
||||
`blender-v4.1-release` it is time to also merge that change to
|
||||
`blender-v4.2-release` it is time to also merge that change to
|
||||
`main`.
|
||||
|
||||
```sh
|
||||
@ -91,8 +91,8 @@ You should have latest `main` now. You can now fetch all the latest
|
||||
change into the release branch, and then merge them into main:
|
||||
|
||||
```sh
|
||||
git fetch origin blender-v4.1-release:blender-v4.1-release
|
||||
git merge blender-v4.1-release
|
||||
git fetch origin blender-v4.2-release:blender-v4.2-release
|
||||
git merge blender-v4.2-release
|
||||
```
|
||||
|
||||
Pay attention to the output. Resolve conflicts if necessary.
|
||||
@ -128,7 +128,7 @@ need to be merged from the release branch. The steps for this are:
|
||||
|
||||
Commit Blender repository changes to release branch:
|
||||
```
|
||||
git checkout blender-v4.1-release
|
||||
git checkout blender-v4.2-release
|
||||
make update
|
||||
git commit sourcefile1 soucefile2
|
||||
```
|
||||
@ -136,7 +136,7 @@ git commit sourcefile1 soucefile2
|
||||
Then commit test files to the release branch.
|
||||
```
|
||||
cd tests/data
|
||||
git checkout blender-v4.1-release
|
||||
git checkout blender-v4.2-release
|
||||
git commit testfile1 testfile2
|
||||
```
|
||||
|
||||
@ -149,9 +149,9 @@ git commit --amend tests/data
|
||||
Check everything is ok, and push both.
|
||||
```
|
||||
cd tests/data
|
||||
git push origin blender-v4.1-release
|
||||
git push origin blender-v4.2-release
|
||||
cd ../..
|
||||
git push origin blender-v4.1-release
|
||||
git push origin blender-v4.2-release
|
||||
```
|
||||
|
||||
#### Merge to Main
|
||||
@ -160,14 +160,14 @@ Merge Blender repository changes into main:
|
||||
```
|
||||
git checkout main
|
||||
make update
|
||||
git merge blender-v4.1-release
|
||||
git merge blender-v4.2-release
|
||||
```
|
||||
|
||||
Merge test data changes into main.
|
||||
```
|
||||
cd tests/data
|
||||
git checkout main
|
||||
git merge blender-v4.1-release
|
||||
git merge blender-v4.2-release
|
||||
```
|
||||
|
||||
Amend Blender repository commit with updated hash.
|
||||
|
||||
@ -4,13 +4,11 @@ This is a checklist to go over when making releases, to ensure everything has be
|
||||
|
||||
`#blender-release` on blender.chat is used for release related communication.
|
||||
|
||||
## Bcon1
|
||||
## Alpha
|
||||
- Check with module teams and developers about large features planned for the new release and add these to the project page.
|
||||
- Decide on a splash screen and deliver it to the release manager before Beta.
|
||||
|
||||
## Bcon2
|
||||
- Decide on a splash screen and deliver it to the release manager before Bcon3.
|
||||
|
||||
## Bcon3
|
||||
## Beta
|
||||
|
||||
Transitioning to the [stabilizing
|
||||
branch](../release_branch.md).
|
||||
@ -22,14 +20,14 @@ branch](../release_branch.md).
|
||||
- Create `blender-v4.XX-release` branches for the following
|
||||
repositories:
|
||||
- `blender.git`
|
||||
- `scripts/addons` (`blender-addons.git`)
|
||||
- `scripts/addons_contrib` (`blender-addons-contrib.git`)
|
||||
- `tests/data` (`blender-test-data.git`)
|
||||
- `release/datafiles/assets` (`blender-assets.git`)
|
||||
- `lib/linux_x64` (`lib-linux_x64.git`)
|
||||
- `lib/windows_x64` (`lib-windows_x64.git`)
|
||||
- `lib/windows_arm64` (`lib-windows_arm64.git`)
|
||||
- `lib/macos_x64` (`lib-macos_x64.git`)
|
||||
- `lib/macos_arm64` (`lib-macos_arm64.git`)
|
||||
- `lib-source.git`
|
||||
- `blender-manual.git`
|
||||
|
||||
```sh
|
||||
@ -79,10 +77,10 @@ branch](../release_branch.md).
|
||||
- Add a new release notes redirect (e.g., `blender.org/download/releases/X.X` -\> `developer.blender.org/docs/release_notes/X.X`)
|
||||
- Create empty release notes for next release on `developer.blender.org/docs/release_notes/` and blender.org
|
||||
- Update dashboard on projects.blender.org
|
||||
- Update bcon in blender.chat topic
|
||||
- Update release phase in blender.chat topic
|
||||
|
||||
|
||||
## Bcon4
|
||||
## Release Candidate
|
||||
|
||||
### Blender
|
||||
- Set `BLENDER_VERSION_CYCLE` to `rc` in the release branch.
|
||||
@ -94,15 +92,15 @@ branch](../release_branch.md).
|
||||
[`release/license/THIRD-PARTY-LICENSES.txt`](third_party_licenses.md)
|
||||
|
||||
### Communication
|
||||
- Write press release and deliver it to the release manager one day before Bcon5.
|
||||
- Write press release and deliver it to the release manager one day before Release.
|
||||
|
||||
## Bcon5
|
||||
## Release
|
||||
|
||||
Preparation for the final release:
|
||||
|
||||
### Communication
|
||||
|
||||
- **At least one hour** before going to BCon5, send message to
|
||||
- **At least one hour** before going to Release phase, send a message to
|
||||
\#blender-coders and check with available core developers online that
|
||||
everything looks good for release.
|
||||
- *Do not do that outside of reasonable work hours CET (10:00-17:00),
|
||||
@ -111,10 +109,10 @@ Preparation for the final release:
|
||||
Bastien Montagne/mont29 so he can update the files prior to final
|
||||
release commits
|
||||
- Move Blender to
|
||||
[**bcon5**](../release_cycle.md#bcon-phases) status:
|
||||
- Update bcon5 status on [\#blender-coders @
|
||||
[**Release**](../release_cycle.md) status:
|
||||
- Update Release status on [\#blender-coders @
|
||||
blender.chat](https://blender.chat/channel/blender-coders)
|
||||
- Update bcon5 status on front page of
|
||||
- Update Release status on front page of
|
||||
[projects.blender.org](https://projects.blender.org/)
|
||||
- Create a *Potential candidates for corrective releases* task tagged
|
||||
with the released version. (For LTS releases, create a *Blender LTS:
|
||||
@ -156,14 +154,16 @@ Tag repositories (only after the build is approved):
|
||||
|
||||
- Tag and push following repositories:
|
||||
- `blender.git`
|
||||
- `scripts/addons` (`blender-addons.git`)
|
||||
- `scripts/addons_contrib` (`blender-addons-contrib.git`)
|
||||
- `scripts/addons` (`blender-addons.git`) (only 3.6)
|
||||
- `scripts/addons_contrib` (`blender-addons-contrib.git`) (only 3.6)
|
||||
- `tests/data` (`blender-test-data.git`)
|
||||
- `release/datafiles/assets` (`blender-assets.git`)
|
||||
- `lib/linux_x64` (`lib-linux_x64.git`)
|
||||
- `lib/windows_x64` (`lib-windows_x64.git`)
|
||||
- `lib/windows_arm64` (`lib-windows_arm64.git`) (4.2 and upwards)
|
||||
- `lib/macos_x64` (`lib-macos_x64.git`)
|
||||
- `lib/macos_arm64` (`lib-macos_arm64.git`)
|
||||
- `lib-source.git`
|
||||
|
||||
```sh
|
||||
git tag -a v3.6.0 -m "Tagging Blender 3.6.0 release"
|
||||
@ -259,8 +259,8 @@ Corrective releases only require:
|
||||
|
||||
#### Release Notes
|
||||
|
||||
- Finish [Release Notes](../../../release_notes/index.md) and update
|
||||
release phase.
|
||||
- Finish [Release Notes](../../../release_notes/index.md), update
|
||||
release phase and [Compatibility Changes](../../../release_notes/compatibility/index.md)
|
||||
- Ensure updated screenshots at
|
||||
<https://download.blender.org/demo/screenshots/>
|
||||
|
||||
@ -280,7 +280,7 @@ Corrective releases only require:
|
||||
- Check manual links are valid in Blender (see
|
||||
[bl_rna_manual_reference.py](https://projects.blender.org/blender/blender/src/branch/main/tests/python/bl_rna_manual_reference.py))
|
||||
|
||||
## Bcon6: LTS
|
||||
## LTS
|
||||
|
||||
In the case of an LTS release, add a new row in Download → Long-term
|
||||
Support → Blender X.X LTS and fill with release notes from
|
||||
@ -330,10 +330,22 @@ too, see `create_release_notes.py`)
|
||||
|
||||
### Blender as Python Module
|
||||
|
||||
- Build and update the python module for PyPI. Note this is not currently done for bugfix/patch releases, due to limited
|
||||
disk space available.
|
||||
- Trigger vXXX-code-daily-coordinator with Python Module and Package Delivery checked
|
||||
- Trigger vXXX-code-bpy-deploy-coordinator
|
||||
Build and update the python module for PyPI. Note this is not currently done for bugfix/patch releases, due to limited disk space available.
|
||||
|
||||
Step 1: Compile the BPY module:
|
||||
|
||||
- Go to the release branch code-daily coordinator, i.e. `v420-code-daily-coordinator`
|
||||
- Click `Trigger Daily Build`
|
||||
- Enable:
|
||||
- Python module
|
||||
- GPU binaries
|
||||
- Package delivery
|
||||
- Wait for the build to finish
|
||||
|
||||
Step 2: Deploy BPY module:
|
||||
|
||||
- Go to the bpy module deployment coordinator, i.e. `v420-code-bpy-deploy-coordinator`
|
||||
- Trigger build
|
||||
|
||||
### Update LTS milestones
|
||||
|
||||
|
||||
@ -30,16 +30,16 @@ Work is done in two branches:
|
||||
|
||||
The `blender-v{VERSION}-release` branch will be available for 6 weeks
|
||||
prior to the release date. At the same time `main` will be open for
|
||||
the next release, giving 12 weeks to add new features for the next
|
||||
release, and another 5 weeks to improve them.
|
||||
the next release, giving 17 weeks to add new features and improve them for the next
|
||||
release.
|
||||
|
||||
## Bcon Phases
|
||||
## Release Phases
|
||||
|
||||
Each Blender version has its own Bcon phase, indicating which types of
|
||||
Each Blender version has its own release phase, indicating which types of
|
||||
changes are allowed to be committed and what developers are focusing on.
|
||||
|
||||
That means for example that Blender 3.4 can be in Bcon3 (bug fixing
|
||||
only) while Blender 3.5 is in Bcon1 (open for new features).
|
||||
That means for example that Blender 4.0 can be in Beta (bug fixing
|
||||
only) while Blender 4.1 is in Alpha (open for new features).
|
||||
|
||||
|
||||
<table markdown>
|
||||
@ -53,61 +53,49 @@ only) while Blender 3.5 is in Bcon1 (open for new features).
|
||||
<td markdown>**Splash Shows**</td>
|
||||
</tr>
|
||||
<tr class="even" markdown>
|
||||
<td rowspan="2">Bcon1</td>
|
||||
<td rowspan="2">Alpha</td>
|
||||
<td rowspan="2">New features and changes</td>
|
||||
<td>6 weeks</td>
|
||||
<td rowspan="2">Add bigger features and merge branches. Risky changes that are
|
||||
likely to cause bugs or additional work must be done before the end of this
|
||||
phase.
|
||||
<td rowspan="2">Add bigger features and merge branches.
|
||||
<br><br>
|
||||
Risky changes that are likely to cause bugs or additional work
|
||||
must be done within the first few weeks of this phase.
|
||||
Afterwards only smaller and less risky changes, including small features, should be made.
|
||||
<br><br>
|
||||
The first 6 weeks overlap with the Beta & Release Candidate phases of the previous
|
||||
release, and many developers will focus on bug fixing.
|
||||
<br><br>
|
||||
If a new feature is too unstable or incomplete, it will be reverted before the
|
||||
end of this phase.
|
||||
<br/><br/>
|
||||
The first 6 weeks overlap with the Bcon3 & Bcon4 phases of the previous
|
||||
release, and many developers will focus on bug fixing in those first weeks.
|
||||
<br/><br/>
|
||||
Developers dedicate a steady 1-2 days/week to the bug tracker, focusing on
|
||||
Developers dedicate a steady 1-3 days/week to the bug tracker, focusing on
|
||||
triaging and newly introduced bugs.
|
||||
</td>
|
||||
<td rowspan="2" markdown>`main`</td>
|
||||
<td rowspan="2">Alpha</td>
|
||||
</tr>
|
||||
<tr class="odd">
|
||||
<td>6 weeks</td>
|
||||
</tr>
|
||||
<tr class="even" markdown>
|
||||
<td>Bcon2</td>
|
||||
<td>Improve and stabilize</td>
|
||||
<td>5 weeks</td>
|
||||
<td>Work to improve, optimize and fix bugs in new and existing features. Only
|
||||
smaller and less risky changes, including small features, should be made in
|
||||
this phase.
|
||||
<br/><br/>
|
||||
If a new feature is too unstable or incomplete, it will be reverted before the
|
||||
end of this phase.
|
||||
<br/><br/>
|
||||
Developers spend 2-3 days/week in the bug tracker, triaging, fixing recently
|
||||
introduced or prioritized module bugs.
|
||||
</td>
|
||||
<td markdown>`main`</td>
|
||||
<td>Alpha</td>
|
||||
<td>11 weeks</td>
|
||||
</tr>
|
||||
<tr class="odd" markdown>
|
||||
<td>Bcon3</td>
|
||||
<td>Beta</td>
|
||||
<td>Bug fixing only</td>
|
||||
<td>5 weeks</td>
|
||||
<td markdown>Focus on bug fixing and getting the release ready.
|
||||
<br/><br/>
|
||||
Development moves to the `blender-v{VERSION}` [release branch](release_branch.md) and the splash screen gets updated. In `main` Bcon1 for the next release starts. `blender-v{VERSION}-release` is regularly merged into `main`.
|
||||
Development moves to the `blender-v{VERSION}` [release branch](release_branch.md) and the splash screen gets updated. In `main` Alpha for the next release starts. `blender-v{VERSION}-release` is regularly merged into `main`.
|
||||
<br/><br/>
|
||||
The Python API remains stable during this phase, so add-ons have time to
|
||||
update before the release.
|
||||
<br/><br/>
|
||||
High priority bugs dictate how much time developers will spend in the tracker
|
||||
as oppose to work on the next release Bcon1 features.
|
||||
as opposed to new features for the next release.
|
||||
</td>
|
||||
<td markdown>`blender-v{VERSION}-release`</td>
|
||||
<td>Beta</td>
|
||||
</tr>
|
||||
<tr class="even" markdown>
|
||||
<td>Bcon4</td>
|
||||
<td>Release Candidate</td>
|
||||
<td>Prepare release</td>
|
||||
<td>1 week</td>
|
||||
<td>Stable branch is frozen to prepare for the release. Only critical and
|
||||
@ -122,23 +110,24 @@ only) while Blender 3.5 is in Bcon1 (open for new features).
|
||||
<td>Release Candidate</td>
|
||||
</tr>
|
||||
<tr class="odd">
|
||||
<td>Bcon5</td>
|
||||
<td>Release</td>
|
||||
<td>Release</td>
|
||||
<td>1-2 days</td>
|
||||
<td>Stage where the final builds are packaged for all platforms, last tweaks
|
||||
to the logs and promotional images, social media, video announcements.
|
||||
<br/><br/>
|
||||
The final switch is flicked on [blender.org](https://www.blender.org) for the new release to show up
|
||||
in the [Download page](https://www.blender.org/download).
|
||||
The final switch is flicked on <a href="https://www.blender.org">blender.org</a> for the new release to show up
|
||||
in the <a href="https://www.blender.org/download">Download page</a>.
|
||||
</td>
|
||||
<td>-</td>
|
||||
<td>-</td>
|
||||
</tr>
|
||||
<tr class="even" markdown>
|
||||
<td>Bcon6 ([LTS](lts.md) only)</td>
|
||||
<td>LTS</td>
|
||||
<td>Long-term release</td>
|
||||
<td>2 years</td>
|
||||
<td markdown>Critical fixes from `main` are ported over after passing quality assurance tests.
|
||||
For actual [LTS releases](lts.md) only.
|
||||
</td>
|
||||
<td markdown>`blender-v{VERSION}-release`</td>
|
||||
<td></td>
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# Python Tests
|
||||
|
||||
Located in:
|
||||
[`tests/python`](http://developer.blender.org/diffusion/B/browse/master/tests/python)
|
||||
[`tests/python`](https://projects.blender.org/blender/blender/src/branch/main/tests/python)
|
||||
|
||||
Execute them directly, or via Blender, the Python files contain info on
|
||||
how to execute in their header.
|
||||
@ -12,10 +12,10 @@ You can run python tests directly from the command line as long as you
|
||||
have python and Blender installed:
|
||||
|
||||
Test file:
|
||||
[tests/python/bl_pyapi_mathutils.py](http://developer.blender.org/diffusion/B/browse/master/tests/python/bl_pyapi_mathutils.py)
|
||||
[tests/python/bl_pyapi_mathutils.py](https://projects.blender.org/blender/blender/src/branch/main/tests/python/bl_pyapi_mathutils.py)
|
||||
|
||||
Source located at:
|
||||
[source/blender/python/mathutils](http://developer.blender.org/diffusion/B/browse/master/source/blender/python/mathutils)
|
||||
[source/blender/python/mathutils](https://projects.blender.org/blender/blender/src/branch/main/source/blender/python/mathutils)
|
||||
|
||||
Execute:
|
||||
|
||||
|
||||
40
docs/handbook/tooling/clog.md
Normal file
40
docs/handbook/tooling/clog.md
Normal file
@ -0,0 +1,40 @@
|
||||
# C/C++ Logging Library (Clog)
|
||||
|
||||
Clog is Blender's own logging library, located in `intern/clog/`. Logging can be enabled by
|
||||
starting Blender with the `--log` command line options. Refer to the [User
|
||||
Manual](https://docs.blender.org/manual/en/dev/advanced/command_line/arguments.html#command-line-args-logging-options)
|
||||
for more options to control the logging via command line arguments.
|
||||
|
||||
## Usage
|
||||
|
||||
- `CLG_LOGREF_DECLARE_GLOBAL` macro to declare `CLG_LogRef` pointers.
|
||||
- `CLOG_` prefixed macros for logging.
|
||||
|
||||
## Identifiers
|
||||
|
||||
`CLG_LogRef` holds an identifier which defines the category of the logger.
|
||||
You can define and use identifiers as needed, logging will lazily initialize them.
|
||||
By convention lower case dot separated identifiers are used, eg:
|
||||
`module.sub_module`, this allows filtering by `module.*`,
|
||||
see `CLG_type_filter_include`, `CLG_type_filter_exclude`.
|
||||
|
||||
There is currently no functionality to remove a category once it's created.
|
||||
|
||||
## Severity
|
||||
|
||||
- `INFO`: Simply log events, uses verbosity levels to control how much information to show.
|
||||
- `WARN`: General warnings (which aren't necessary to show to users).
|
||||
- `ERROR`: An error we can recover from, should not happen.
|
||||
- `FATAL`: Similar to assert. This logs the message, then a stack trace and abort.
|
||||
|
||||
## Verbosity Level
|
||||
|
||||
Usage:
|
||||
|
||||
| Level | Description |
|
||||
| ----- | ------------|
|
||||
| 0 | Always show (used for warnings, errors). Should never get in the way or become annoying. |
|
||||
| 1 | Top level module actions (eg: load a file, create a new window .. etc). |
|
||||
| 2 | Actions within a module (steps which compose an action, but don't flood output). Running a tool, full data recalculation. |
|
||||
| 3 | Detailed actions which may be of interest when debugging internal logic of a module. These *may* flood the log with details. |
|
||||
| 4+ | May be used for more details than 3, should be avoided but not prevented. |
|
||||
@ -3,6 +3,7 @@
|
||||
- [Address Sanitizer](asan.md)
|
||||
- [Valgrind](valgrind.md)
|
||||
- [GDB](gdb.md)
|
||||
- [Clog: C/C++ Logging Library](clog.md)
|
||||
- [Doxygen](doxygen.md)
|
||||
- Python
|
||||
- [Profiling](python_profile.md)
|
||||
|
||||
@ -207,6 +207,12 @@ Blender’s translations API is also [exposed in
|
||||
Python](https://docs.blender.org/api/current/bpy.app.translations.html)
|
||||
(`bpy.app.translations`), to be used by UI scripts and addons!
|
||||
|
||||
!!! warning "No 'f-string'"
|
||||
There should be no 'f-string' type of formatting used in translatable
|
||||
Python strings. These are not actual strings, and cannot be processed
|
||||
neither by the i18n messages extraction tools, nor the `gettext` backend
|
||||
used to find a valid translation.
|
||||
|
||||
> NOTE: **Python translations**
|
||||
> Translations of all “internal” scripts, as well as for OFFICIAL
|
||||
addons, is handled by the main (core) translations project
|
||||
|
||||
@ -49,7 +49,8 @@ And sometimes, a message is just wrong, has a typo, or is not very
|
||||
clear, even in English.
|
||||
|
||||
If any such issue arises, please notify developers in [this
|
||||
task](https://projects.blender.org/blender/blender/issues/43295).
|
||||
task](https://projects.blender.org/blender/blender/issues/43295) or
|
||||
[the chat](https://blender.chat/channel/translations).
|
||||
|
||||
### About Translating "Blender"
|
||||
|
||||
@ -159,12 +160,6 @@ removed.
|
||||
> NOTE: Using a dedicated editor for po files is recommended, like e.g.
|
||||
Poedit.
|
||||
|
||||
#### Edit Translations from Blender - Translators
|
||||
|
||||
> NOTE: **Currently Unavailable**
|
||||
> The move to git repository and weblate web interface requires some
|
||||
updates to the add-on before this feature can be used again.
|
||||
|
||||
#### Add New Languages - Translators
|
||||
|
||||
Adding a language has to be done by an admin/developer of the project.
|
||||
@ -365,9 +360,9 @@ matches the original text, or to reload it by toggling twice.
|
||||
`none` by `wm.context_toggle_enum`.
|
||||
- In the `Context Attributes` field, enter
|
||||
`preferences.view.language`.
|
||||
- In the `Value` fields, enter `DEFAULT` and the desired language
|
||||
- In the `Value` fields, enter `en_US` and the desired language
|
||||
code (for instance, `pt_BR`; you can get the code in the
|
||||
`Translation` preferences by hovering the `Language` field).
|
||||
`Translation` preferences, in the tooltip for the `Language` field).
|
||||
- Assign the shortcut to a free combination, for instance
|
||||
<span class="hotkeybg">
|
||||
<span class="hotkey">Ctrl</span>
|
||||
@ -383,6 +378,7 @@ matches the original text, or to reload it by toggling twice.
|
||||
### Language teams
|
||||
|
||||
- [French team](french_team.md)
|
||||
- [Spanish team](spanish_team.md)
|
||||
|
||||
### Local blender.chat channels
|
||||
|
||||
|
||||
BIN
docs/images/Blender_release_cycle_01.png
(Stored with Git LFS)
BIN
docs/images/Blender_release_cycle_01.png
(Stored with Git LFS)
Binary file not shown.
BIN
docs/images/VSE42MissingMedia.png
(Stored with Git LFS)
BIN
docs/images/VSE42MissingMedia.png
(Stored with Git LFS)
Binary file not shown.
BIN
docs/images/design_A4_asset_bundle.jpg
(Stored with Git LFS)
Normal file
BIN
docs/images/design_A4_asset_bundle.jpg
(Stored with Git LFS)
Normal file
Binary file not shown.
BIN
docs/images/design_A4_hair.jpg
(Stored with Git LFS)
Normal file
BIN
docs/images/design_A4_hair.jpg
(Stored with Git LFS)
Normal file
Binary file not shown.
BIN
docs/images/design_A4_spreadsheet_presentation.jpg
(Stored with Git LFS)
Normal file
BIN
docs/images/design_A4_spreadsheet_presentation.jpg
(Stored with Git LFS)
Normal file
Binary file not shown.
BIN
docs/images/design_example_asset_metadata.png
(Stored with Git LFS)
Normal file
BIN
docs/images/design_example_asset_metadata.png
(Stored with Git LFS)
Normal file
Binary file not shown.
BIN
docs/images/design_examples_database-asset.png
(Stored with Git LFS)
Normal file
BIN
docs/images/design_examples_database-asset.png
(Stored with Git LFS)
Normal file
Binary file not shown.
@ -44,6 +44,7 @@ hide:
|
||||
or check out the latest and greatest.
|
||||
|
||||
[:octicons-arrow-right-24: Release Notes](release_notes/index.md)
|
||||
[:octicons-arrow-right-24: Compatibility Changes](release_notes/compatibility/index.md)
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
@ -43,8 +43,8 @@ by **David Zhang**<br>
|
||||
*Mentor:* Sybren Stüvel<br>
|
||||
*Code:* tba
|
||||
|
||||
- Proposal and
|
||||
Reports
|
||||
- [Proposal and
|
||||
Reports](https://devtalk.blender.org/t/gsoc-2024-improve-distributed-rendering-task-execution/34566)
|
||||
|
||||
### Improvements to the Blender macOS User Interface Experience
|
||||
|
||||
@ -70,8 +70,8 @@ by **John Kiril Swenson**<br>
|
||||
*Mentor:* Aras Pranckevičius<br>
|
||||
*Code:* tba
|
||||
|
||||
- Proposal and
|
||||
Reports
|
||||
- [Proposal and
|
||||
Reports](https://devtalk.blender.org/t/gsoc-2024-sprucing-up-the-video-sequencer-weekly-reports/34545)
|
||||
|
||||
### UV stitch Tool Improvements
|
||||
|
||||
@ -79,5 +79,5 @@ by **Anish Bharadwaj**<br>
|
||||
*Mentors:* Campbell Barton<br>
|
||||
*Code:* tba
|
||||
|
||||
- Proposal and
|
||||
Reports
|
||||
- [Proposal and
|
||||
Reports](https://devtalk.blender.org/t/gsoc-2024-uv-stitching-improvements/34523)
|
||||
|
||||
@ -28,7 +28,7 @@ network handles and website.
|
||||
blender.chat](https://blender.chat/channel/blender-coders), let us know your
|
||||
nickname.
|
||||
If you have a web page you'd like us to know about, please include it.
|
||||
You can mention your Facebook, Twitter or other identities!
|
||||
You can also mention your social media profiles.
|
||||
|
||||
### Synopsis
|
||||
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
- [Getting Started](getting_started.md)
|
||||
- [Project Ideas](ideas.md)
|
||||
- [Application Template](application_template.md)
|
||||
- [2024](2024.md)
|
||||
- Previous Years
|
||||
- [2023](2023.md)
|
||||
- [2022](2022.md)
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
|
||||
Blender 3.3 LTS was released on September 7, 2022.
|
||||
|
||||
It will be maintained until September 2024.
|
||||
|
||||
Check out out the final [release notes on
|
||||
blender.org](https://www.blender.org/download/releases/3-3/).
|
||||
|
||||
|
||||
@ -2,6 +2,8 @@
|
||||
|
||||
Blender 3.6 LTS was released on June 27, 2023.
|
||||
|
||||
It will be maintained until June 2025.
|
||||
|
||||
Check out out the final [release notes on
|
||||
blender.org](https://www.blender.org/download/releases/3-6/).
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ to reduce GPU memory usage at the cost of slower denoising.
|
||||
* Apple Silicon with macOS version 13.0 and newer
|
||||
|
||||
For AMD GPUs, it is currently not enabled due to stability issues. However it can be tested in
|
||||
[daily Blender 4.2 builds](https://builder.blender.org/download/daily/).
|
||||
[daily Blender 4.2 LTS builds](https://builder.blender.org/download/daily/).
|
||||
There it is supported for AMD RDNA2 and RDNA3 generation discrete GPUs.
|
||||
|
||||
### Benchmark
|
||||
|
||||
@ -1,16 +0,0 @@
|
||||
# Blender 4.2: Add-ons
|
||||
|
||||
## 3DS
|
||||
|
||||
- Import is now possible by drag & drop from desktop window.
|
||||
(blender/blender-addons@79077f3b7f)
|
||||
- Multiple selected files can now be imported.
|
||||
(blender/blender-addons!105227)
|
||||
- Added option to create new collections for imported files.
|
||||
(blender/blender-addons!105232)
|
||||
- Enabled the collection exporter feature.
|
||||
(blender/blender-addons@8250852c04)
|
||||
- Added support to export non-mesh objects.
|
||||
(blender/blender-addons@540de86d70)
|
||||
- Improved importing bitmap and gradient world nodes setup.
|
||||
(blender/blender-addons@e8c1acd430)
|
||||
@ -1,33 +1,43 @@
|
||||
# Blender 4.2: Animation & Rigging
|
||||
# Blender 4.2 LTS: Animation & Rigging
|
||||
|
||||
## Motion Paths
|
||||
- Motion Path points now use the Vertex theme color (blender/blender@fc025abde6).
|
||||
- You can now specify a custom color for anything before or after the current frame. Previously this was a single color (blender/blender@883af6dd63).
|
||||
|
||||
## Animation Editors
|
||||
- New operator in the View (regular + pie) menu: "Frame Scene Range" (blender/blender@95966813ae58).
|
||||
This changes the horizontal view to match the scene range. If the [preview range][preview-range]
|
||||
is active, the operator will be re-labeled as "Frame Preview Range" and zoom to that instead. This
|
||||
was added to the Dope Sheet, Timeline, Graph Editor, NLA Editor, and Video Sequence Editor.
|
||||
|
||||
[preview-range]: https://docs.blender.org/manual/en/4.2/editors/timeline.html#frame-controls
|
||||
|
||||
## Graph Editor
|
||||
- Modified the way the Ease operator works. It now creates an S-Curve shape that can be moved to
|
||||
favor either the left or the right end. In addition to that, a "Sharpness" property was added to
|
||||
control how abrupt the change is. Pressing `Tab` while running the operator toggles which property the slider affects. (blender/blender@62f140e048,
|
||||
[Manual](https://docs.blender.org/manual/en/4.2/editors/graph_editor/fcurves/editing.html#ease)).
|
||||
- The drawing code has been optimized resulting in smoother panning in heavy scenes. (blender/blender@3eda9619f9, blender/blender@0157fede80)
|
||||
- Performance when moving keys in heavy scenes has been drastically improved.
|
||||
Previous Blender versions could hang for minutes while it is instantaneous in 4.2.
|
||||
The more keys the scene has the more pronounced the effect is.(blender/blender@8a79212031, blender/blender@6a55a126e9, blender/blender@c6c7d3d8c4, blender/blender@08de3fa0b6)
|
||||
- Performance when moving keys in heavy scenes has been drastically improved. Previous Blender
|
||||
versions could hang for minutes while it is instantaneous in 4.2. The more keys the scene has the
|
||||
more pronounced the effect is.(blender/blender@8a79212031, blender/blender@6a55a126e9,
|
||||
blender/blender@c6c7d3d8c4, blender/blender@08de3fa0b6)
|
||||
|
||||
<figure>
|
||||
<video src="graph_editor_speedup.mp4" title="Performance comparison between 3.6 and 4.2" width="720" controls=""></video>
|
||||
<video src="../videos/anim_graph_editor_speedup.mp4" title="Performance comparison between 3.6 and 4.2" width="720" controls=""></video>
|
||||
<figcaption>Comparison of moving 300 keys in a 10,000 frame file 5 frames to the right.</figcaption>
|
||||
</figure>
|
||||
|
||||
|
||||
## Dope Sheet
|
||||
|
||||
|
||||
|
||||
|
||||
- New key type: 'Generated' (blender/blender@51e1f29a68). This new key type indicates that the key
|
||||
was set by some automated tool (like an add-on), rather than manually by an animator. It is drawn
|
||||
smaller & dimmed in the Dope Sheet. These keys can still be operated on like any other, including
|
||||
changing their key type to something else.
|
||||
- It is now possible to see and edit non relative shape key animations in the "Shape Key Editor". (blender/blender@7ff8a7b173)
|
||||
|
||||
|
||||
## NLA
|
||||
- Performance of the editor has been improved when only viewing a section of a long action
|
||||
@ -39,9 +49,19 @@ The more keys the scene has the more pronounced the effect is.(blender/blender@8
|
||||
- Subdividing a bone names the new bones in sequential order (blender/blender@9f0cc7fe64).
|
||||
Subdividing "Bone" makes "Bone.001" its first child, "Bone.002" the next, etc. Previously this
|
||||
would have been "Bone", "Bone.003", "Bone.002", "Bone.001".
|
||||
- It is now possible to specify a wire width for custom bone shapes. This setting is per bone and can be found under the "Custom Shape" options of the bone (blender/blender@f9ea64b0ba). There is a known visual issue on vertex corners where the edges detach instead of forming a round corner. Work to mitigate this [has been underway](https://projects.blender.org/blender/blender/pulls/122481) but it was decided to wait until the overlay engine had an overhaul.
|
||||
- Bones can now be active even if they are invisible. That means you can select a bone from the outliner and edit its properties without having to unhide it. This was done in reaction to a [bug report](https://projects.blender.org/blender/blender/issues/116138). (blender/blender@1ab66a6b4f)
|
||||
- The Armature drawing mode "Stick" now uses bone colors (blender/blender@ef8f14f3d6).
|
||||
|
||||
<figure>
|
||||
<video src="../videos/anim_bone_wire_width.mp4" title="Bone wire width demo" width="720" controls=""></video>
|
||||
<figcaption>Added the option to define the wire width of custom bone shapes.</figcaption>
|
||||
</figure>
|
||||
|
||||
## Constraints
|
||||
- The behavior of the "Limit Rotation" constraint has been modified to fix a bug ([Bug Report](https://projects.blender.org/blender/blender/issues/117927), blender/blender@ed2408400d). In older versions the constrained object would flip back to the minimum when an angle is higher than 180º. This is now changed so values higher than 180º are supported. This means a minimum of 90º and a maximum of 270º now works properly. Also instead of snapping back to the minimum, the rotation will snap to the closest boundary when the rotation is out of the allowed range. Rigs relying on the old behavior of snapping back to the minimum might not work as expected.
|
||||
- The behavior of the "Limit Rotation" constraint has been modified to fix a bug ([Bug Report](https://projects.blender.org/blender/blender/issues/117927), blender/blender@ed2408400d). In older versions the constrained object would flip back to the minimum when an angle is higher than 180º. This is now changed so values higher than 180º are supported. This means a minimum of 90º and a maximum of 270º now works properly. Also instead of snapping back to the minimum, the rotation will snap to the closest boundary when the rotation is out of the allowed range.
|
||||
|
||||
Since older files may rely on the previous broken behavior, a "Legacy Behavior" option has also been added to the constraint. "Limit Rotation" constraints from old blend files will automatically have that option enabled to preserve behavior, but users are encouraged to update their rigs to work with the new fixed behavior.
|
||||
|
||||
## Drivers
|
||||
- A new "Copy Driver to Selected" menu item is now available in the right-click
|
||||
@ -57,7 +77,7 @@ Copy Global Transform ([manual][copy-global-transform-doc]) has gotten two new,
|
||||
|
||||
[copy-global-transform-doc]: https://docs.blender.org/manual/en/latest/addons/animation/copy_global_transform.html
|
||||
|
||||
|
||||
|
||||
|
||||
### Fix to Camera
|
||||
|
||||
@ -76,9 +96,12 @@ The "Relative" panel has copy/paste buttons that work relative to some object. T
|
||||
be chosen in the panel. If no object is chosen, the copy/paste will happen relative to the active
|
||||
scene camera.
|
||||
|
||||
## Pose Library
|
||||
|
||||
Added an option to "Blend Pose Flipped" from the context menu. Previously this was only available during modal operations. (blender/blender@3a40d2813f)
|
||||
|
||||
Pressing `Ctrl` before dragging on a Pose Library item now starts it in flipped mode. Previously this was only possible once the blending operation has started. (blender/blender@345cd70404)
|
||||
|
||||
## Python API
|
||||
- `rna_struct.keyframe_insert()` now has a new, optional keyword argument `keytype` to set the key type
|
||||
(blender/blender@1315991ecbd179bbff8fd08469dda61ec830d72f). This makes it possible to set the new
|
||||
key's type directly. Example: `bpy.context.object.keyframe_insert("location", keytype='JITTER')`.
|
||||
- There is a new function on the F-Curve: `bake`. This creates keys at a given interval for a given range on the existing curve
|
||||
(blender/blender@20a4c9c928).
|
||||
|
||||
See [Animation in the Python API section](python_api.md#animation).
|
||||
@ -1,10 +1,28 @@
|
||||
# Blender 4.2: Compositor
|
||||
# Blender 4.2 LTS: Compositor
|
||||
|
||||
## GPU Acceleration
|
||||
|
||||
Compositing for final renders can now be GPU-accelerated (blender/blender@727a90a0f17).
|
||||
|
||||
The device used for compositing is configured in either `Render settings -> Performance -> Compositor`,
|
||||
or in the properties panel of the Compositor editor. It is expected that CPU and GPU compositor evaluation
|
||||
gives the same results, with minimal differences between devices.
|
||||
|
||||
## CPU Optimizations
|
||||
|
||||
The render compositor CPU backend has also been rewritten to improve performance,
|
||||
often making it several times faster than before.
|
||||
|
||||
There are some changes in behavior. These were made so that the final render and
|
||||
3D viewport compositor work consistently, and can run efficiently on the GPU.
|
||||
Manual adjustments might be necessary to get the same result as before. See the
|
||||
**Breaking Changes** section below for details.
|
||||
|
||||
## Added
|
||||
|
||||
- Added an overlay to display each node's last execution time. The display of execution time is
|
||||
disabled by default, and can be enabled from the Overlays pop-over.
|
||||
The execution time statistics is gathered during compositor evaluation in the nodes editor.
|
||||
The execution time statistics are gathered during compositor evaluation in the nodes editor.
|
||||
(blender/blender@467a132166)
|
||||
- The *Legacy Cryptomatte* node is now supported in the *Viewport Compositor*.
|
||||
(blender/blender@2bd80f4b7a)
|
||||
@ -17,9 +35,15 @@
|
||||
(blender/blender@382131fef2)
|
||||
- The *Translate* node now has an *Interpolation* option that allows choosing between *Nearest*,
|
||||
*Bilinear*, and *Bicubic*. (blender/blender@483c854612)
|
||||
- The *Fog Glow* mode of the *Glare* node is now implemented for the viewport compositor, albeit
|
||||
with a slow CPU-based implementation for now. (blender/blender@f0c379e1d3)
|
||||
|
||||
## Changed
|
||||
## Improved
|
||||
|
||||
- The *Fog Glow* mode of the *Glare* node is now up to 25x faster. (blender/blender@d4bf23771d)
|
||||
- In the viewport compositor, the compositing space is now always limited to the camera region
|
||||
in camera view regardless of the passepartout value. This means areas outside of the camera will
|
||||
not be composited, but the result will match the final render better.
|
||||
- The *Hue Correct* node now evaluates the saturation and value curves at the original input hue,
|
||||
not the updated one resulted from the evaluation of the hue curve. (blender/blender@69920a0680)
|
||||
- The *Hue Correct* node now wraps around, so discontinuities at the red hue will no longer be an
|
||||
@ -28,24 +52,17 @@
|
||||
image boundary are the same color as their closest boundary pixels. While it previously ignored
|
||||
such pixels and adjusted blur weights accordingly. (blender/blender@c409f2f7c6)
|
||||
- The *Vector Blur* node was rewritten to match EEVEE's motion blur. The Curved, Minimum, and
|
||||
Maximum options were removed but might be restored later. (blender/blender@b229d32086)
|
||||
Maximum options were removed. (blender/blender@b229d32086)
|
||||
- The *Fast Gaussian* mode of the *Blur* node now matches the size of other modes of blur, while it
|
||||
was previously larger in size. (blender/blender@f595345f52)
|
||||
- The *Bicubic* interpolation mode of the *Rotate* and *Stabilize 2D* nodes is now implemented as
|
||||
a bicubic b-spline interpolation, while previously it used bilinear. (blender/blender@f1d4859e2a)
|
||||
- The *Update Views* button was removed from the *Switch View* node, and the updates now happen
|
||||
automatically. (blender/blender@9484770551)
|
||||
|
||||
## Improved Render Compositor
|
||||
## Breaking Changes
|
||||
|
||||
The render compositor has been rewritten to improve performance, often making it
|
||||
several times faster than before.
|
||||
|
||||
The compositor currently works on the CPU, but GPU acceleration is coming soon as well.
|
||||
|
||||
There are some changes in behavior. These were made so that the final render and
|
||||
3D viewport compositor work consistently, and can run efficiently on the GPU.
|
||||
Manual adjustments might be necessary to get the same result as before.
|
||||
|
||||
This mainly affects canvas and single-value handling: the new implementation
|
||||
The changes mainly affects canvas and single-value handling: the new implementation
|
||||
follows strict left-to-right node evaluation, including canvas detection. This
|
||||
makes relative transform behave differently in some cases, and makes it so
|
||||
single value inputs (such as RGB Input) can not be transformed as image.
|
||||
@ -61,9 +78,9 @@ it was necessary to apply them. This is demonstrated in the following example, w
|
||||
scaled down then scaled up again. Since the scaling was delayed in the old compositor, the image
|
||||
didn't loose any information, while in the new compositor, the image was pixelated.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Repetition
|
||||
|
||||
@ -73,9 +90,9 @@ example, where an image gets Wrapping enabled then scaled down. For the old comp
|
||||
wrapping was delayed until the scale down node, producing repetitions. While in the new compositor,
|
||||
wrapping only effects the translate node, which does nothing, so it is unaffected.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
NOTE: This functionality will be restored in the future in a more explicit form.
|
||||
|
||||
@ -94,9 +111,9 @@ input, which is transformation-less, similarly, the blur node also treated its i
|
||||
red value, which was passed through without blurring, and finally, the color mix node when
|
||||
receiving a single red color, mixed it with the entire mandrill image as most nodes do.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Clipping
|
||||
|
||||
@ -104,9 +121,9 @@ The old compositor will clip images if their inferred size is smaller than their
|
||||
the new compositor will not do size inference and consequently will not clip images. This is
|
||||
demonstrated in the following example.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Sampling Space
|
||||
|
||||
@ -117,6 +134,11 @@ a scaled up image is sampled in its entirety by using normalized [0, 1] gradient
|
||||
coordinates. The old compositor produced clipped mages since its inferred size is also clipped,
|
||||
while the new compositor produces full images.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### Removed
|
||||
|
||||
- `Two Pass` options has been removed (blender/blender@6db8091f458e)
|
||||
- Edit and Render quality options have been removed (blender/blender@9532ea3f8c29, blender/blender@149e547de69c)
|
||||
|
||||
@ -1,10 +1,35 @@
|
||||
# Blender 4.2: Core
|
||||
|
||||
## Command Line Arguments
|
||||
|
||||
- Running in background-mode using `-b` or `--background` now disables audio by default
|
||||
(blender/blender@7c90018f2300646dbdec2481b896999fe93e6e62).
|
||||
# Blender 4.2 LTS: Core
|
||||
|
||||
## Undo
|
||||
|
||||
- Faster undo due to implicit sharing (blender/blender@0e8e219d71cd27cf025a9920ac4fb54ff7c178b3).
|
||||
- Faster undo due to implicit sharing. (blender/blender@0e8e219d71cd27cf025a9920ac4fb54ff7c178b3)
|
||||
|
||||
## Portable Installation
|
||||
|
||||
- Creating a
|
||||
[portable installation](https://docs.blender.org/manual/en/4.2/advanced/blender_directory_layout.html#portable-installation)
|
||||
now works by creating a folder named `portable` next to the Blender executable,
|
||||
instead of a `4.2/config` folder. (blender/blender!122778)
|
||||
|
||||
## Environment Variables
|
||||
|
||||
- The new `BLENDER_SYSTEM_EXTENSIONS` environment variable adds extensions to a
|
||||
Blender installation. See the
|
||||
[Deploying Blender in Production](http://docs.blender.org/manual/en/4.2/advanced/deploying_blender.html)
|
||||
documentation for details. (blender/blender!122832)
|
||||
- The existing `BLENDER_SYSTEM_SCRIPTS` environment variable will now
|
||||
always add scripts likes legacy add-ons and presets to a Blender installation.
|
||||
This can be used for example in an animation studio to make scripts available to all users.
|
||||
Previously this environment variable often either did not work or behaved inconsistently.
|
||||
(blender/blender!122689)
|
||||
|
||||
## Command Line Arguments
|
||||
|
||||
- Running in background-mode using `-b` or `--background` now disables audio by default.
|
||||
(blender/blender@7c90018f2300646dbdec2481b896999fe93e6e62)
|
||||
- New `--online-mode` and `--offline-mode` arguments to force Blender to
|
||||
enable or disable online access, overriding the preferences.
|
||||
(blender/blender!121994)
|
||||
- Extensions can be managed via the command line using the
|
||||
[extension](https://docs.blender.org/manual/en/4.2/advanced/command_line/extension_arguments.html)
|
||||
sub-command (blender/blender@13a3603578f87ee47eb69e26271dc67d2d7df209)
|
||||
|
||||
@ -1,13 +1,52 @@
|
||||
# Blender 4.2: Cycles
|
||||
# Blender 4.2 LTS: Cycles
|
||||
|
||||
## Ray Portals
|
||||
|
||||
The Ray Portal BSDF transports rays to another location in the scene, with specified ray position and normal. It can be used to render portals for visual effects, and other production rendering tricks. (blender/blender!114386)
|
||||
|
||||
See the [documentation](https://docs.blender.org/manual/en/4.2/render/shader_nodes/shader/ray_portal.html) for details and example node setups.
|
||||
|
||||
|
||||
|
||||
|
||||
## Thin Film Interference
|
||||
|
||||
The Principled BSDF now supports physically accurate thin film interference effects for specular reflection and transmission. (blender/blender!118477)
|
||||
|
||||
Initially, this is only applied to dielectric materials, support for metallic thin film effects is planned later. Similarly, the effect is not yet supported by EEVEE.
|
||||
|
||||
|
||||
|
||||
## Shaders
|
||||
|
||||
* [Ray Portal BSDF](https://docs.blender.org/manual/en/4.2/render/shader_nodes/shader/ray_portal.html): Transport rays to another location in the scene, with specified ray position and normal. It can be used to render portals for visual effects, and other production rendering tricks. (blender/blender!114386)
|
||||
* Principled Hair with the Huang model now provides more accurate results when viewing hairs close up, by dynamically switching between a near and far field model depending on the distance. (blender/blender!116094)
|
||||
* Subsurface Scattering node now has a Roughness input, matching the Principled BSDF. (blender/blender!114499)
|
||||
|
||||
## Denoising
|
||||
|
||||
* Upgrade OpenImageDenoise to version 2.3, with improved denoising quality.
|
||||
* GPU acceleration is now enabled on AMD GPUs on Windows and Linux.
|
||||
* CPU renders can now also use GPU accelerated denoising. (blender/blender!118841)<br/>
|
||||
The denoiser uses GPU device configured in the User Preferences. The side-effect of this is that
|
||||
OptiX denoiser requires having OptiX compute device configured in the preferences.
|
||||
|
||||
## Sampling
|
||||
|
||||
* Blue noise dithered sampling to improve the visual quality of renders. This mainly helps when setting the maximum number of samples to a low number, and for interactive viewport renders. New files use this mode by default, while existing files can be changed in the Sampling → Advanced panel. (blender/blender!123274)
|
||||
|
||||
| |Classic|Blue Noise|
|
||||
|-|-|-|
|
||||
|Raw|||
|
||||
|Denoised|||
|
||||
|
||||
* Improved volume light sampling, particularly for spot lights and area light spread. (blender/blender!119438) (blender/blender!122667)
|
||||
|
||||
## Other
|
||||
|
||||
* Improved volume light sampling, particularly for spot lights and area light spread. (blender/blender!119438)
|
||||
* World Override option for view layers. (blender/blender!117920)
|
||||
* OpenImageDenoise is now GPU accelerated on AMD GPUs on Windows and Linux.
|
||||
* Intel GPU rendering now supports host memory fallback. (blender/blender!122385)<br/>
|
||||
Drivers 101.5518-101.5525 and 101.5768 and higher are currently recommended for this feature. (blender/blender#124763)
|
||||
* GPU kernels are now compressed, reducing Blender installation size. (blender/blender!123557)
|
||||
* Motion Blur settings are now shared with EEVEE. (blender/blender@74b8f99b43)
|
||||
* Embree has been updated to 4.3.2 (blender/blender!122242) which relies on more driver components to provide Hardware Ray-tracing:<br/>
|
||||
Intel GPU users on Linux should ensure [intel-level-zero-gpu-raytracing](https://github.com/intel/level-zero-raytracing-support/releases) package is installed as mentioned in the [documentation](https://dgpu-docs.intel.com/driver/client/overview.html).
|
||||
@ -1,7 +1,109 @@
|
||||
# Blender 4.2: EEVEE & Viewport
|
||||
# Blender 4.2 LTS: EEVEE
|
||||
|
||||
## Viewport Compositor
|
||||
The EEVEE render engine was rewritten to allow deeper changes, removing long standing limitations and facilitating future evolution.
|
||||
|
||||
- The compositing space is now always limited to the camera region in camera view regardless of the
|
||||
passepartout value. Which means areas outside of the camera will not be composited,
|
||||
but the result will match the final render better.
|
||||
## Migrating from Older Versions
|
||||
Most scenes should be automatically adjusted to keep the same look. However, there are some cases that need manual adjustments.
|
||||
See **[migration process](eevee_migration.md)** for more details.
|
||||
|
||||
## Global Illumination
|
||||
EEVEE now uses screen space ray tracing for every BSDF. There is no longer any limitation to the number of BSDFs.
|
||||
|
||||
Materials using the `Blended` render method are now removed from reflections instead of being projected onto the background. [See the manual](https://docs.blender.org/manual/en/4.2/render/eevee/render_settings/raytracing.html#fast-gi-approximation).
|
||||
|
||||
## Lights
|
||||
There is no longer a limit to the number of lights in a scene. However, only 4096 lights can be visible at the same time.
|
||||
|
||||
- Lights are now visible through refractive surfaces. A new transmission influence factor has been added and set to 0 for older files.
|
||||
- Lights now support ray visibility options.
|
||||
- Glossy lighting no longer leaks at the back of objects.
|
||||
|
||||
## Shadows
|
||||
Shadows are now rendered using Virtual Shadow Maps. This greatly increases the maximum resolution, reduces biases and simplifies the setup.
|
||||
|
||||
- Light visibility is now computed using Shadow Map Ray Tracing, providing plausible soft shadows without needing shadow jittering.
|
||||
- Shadow Map biases have been removed and are now computed automatically. A workaround for the shadow terminator issue is planned for future releases.
|
||||
- Contact shadows have been removed since Virtual Shadow Maps are precise enough in most cases.
|
||||
- Shadow clip start has been removed and replaced by an automatic value.
|
||||
|
||||
## Shading
|
||||
### Shading Modes
|
||||
`Material > Blend Mode` was replaced by `Material > Render Method`. `Blended` corresponds to the former `Alpha Blend`.
|
||||
`Material > Shadow Mode` was replaced by `Object > Visibility > Ray Visibility > Shadow` at the object level.
|
||||
|
||||
A `Backface Culling` option for shadow and a `Transparent Shadows` option were added to reduce the performance impact of rendering Virtual Shadow Maps.
|
||||
|
||||
Shadows and surfaces with the `Dithered` render method behave the same as the former `Alpha Hashed` method. To reproduce the same behavior as the former `Alpha Clip` option, materials need be modified by adding a `Math` node with mode `Greater Than`.
|
||||
|
||||
`Blended` materials now have correct rendering ordering of their opaque pixels.
|
||||
|
||||
The `Screen-Space Refraction` option was renamed to `Raytraced Transmission` and affects all transmissive BSDF nodes (Translucent BSDF, Subsurface Scattering, Refraction BSDF, ...).
|
||||
|
||||
### Displacement
|
||||
Displacement is now supported with the exception of the `Displacement Only` mode which falls back to `Displacement And Bump`. [See the manual](https://docs.blender.org/manual/en/4.2/render/materials/components/displacement.html#displacement-and-bump)
|
||||
|
||||
### Thickness
|
||||
A new Thickness output has been introduced. This allows better modeling of Refraction, Subsurface Scattering and Translucency. Some materials might need adjustment to keep the same appearance. This replaces the former `Refraction Depth` option. (blender/blender!120384)
|
||||
|
||||
### Subsurface Scattering
|
||||
The new Subsurface Scattering implementation supports any number of BSSRDF nodes with arbitrary radii.
|
||||
Subsurface Scattering no longer leaks between objects and has no energy loss.
|
||||
|
||||
Subsurface translucency is always computed and the associated option has been removed.
|
||||
|
||||
## Light Probes
|
||||
The render panel options have been split between the light probe data panel and the world data panel.
|
||||
|
||||
### Volume Light Probes
|
||||
The new volume light probes baking converges faster with higher resolutions.
|
||||
|
||||
Baking is now done at the object level, allowing volume light probes to be edited after baking and linked from other files. Optionally they can bake sky visibility for dynamic sky lighting.
|
||||
|
||||
There is a new rejection algorithm and flood fill to reduce shadow leaking.
|
||||
|
||||
Volume light probes now affect volume shading. However object volumes and world volumes are not yet captured by the volume light probes.
|
||||
|
||||
### Sphere Light Probes
|
||||
Sphere light probes are now dynamic and get updated as they move.
|
||||
Filtered versions for rough surfaces are now firefly-free. The look of the reflections can appear less "foggy" than in the previous EEVEE version.
|
||||
|
||||
## Volumes
|
||||
World volumes are no longer limited to clipping distance, which means they can completely block sun lights and the world background. Older file can be converted using the conversion operator in the Help menu or in the `World > Volume` panel. (blender/blender!114062)
|
||||
|
||||
- Volume lighting is now dithered to avoid flickering.
|
||||
- EEVEE now maximizes the depth range automatically if no world is present.
|
||||
- Mesh objects now have correct volume intersection instead of rendering bounding boxes.
|
||||
- Evaluation of many small volume objects has been optimized.
|
||||
|
||||
## World
|
||||
Sun light contribution is now automatically extracted from HDRI lighting. [See the manual](https://docs.blender.org/manual/en/4.2/render/eevee/world_settings.html#sun).
|
||||
|
||||
## Image Stability
|
||||
Improvements in viewport image stability through velocity-aware temporal supersampling should help reduce the noise and aliasing issues that were previously present.
|
||||
|
||||
Clamping options have been enhanced to help prevent fireflies and to better match Cycles. The properties remain independent for each renderer.
|
||||
|
||||
## Motion Blur
|
||||
Motion blur is now partially supported in the viewport, through the camera view.
|
||||
|
||||
Shutter curves are now supported.
|
||||
|
||||
|
||||
## Depth of Field
|
||||
Depth of field was rewritten and optimized, removing the `Denoise Amount` and `High Quality Slight Defocus` settings which are now always on.
|
||||
|
||||
## User Interface
|
||||
- The panels and properties have been adjusted to be closer to Cycles.
|
||||
- The object `Display As` property set to `Wire` or `Bounds` will now render in `Render` viewport shading mode. (blender/blender@1f2b935146)
|
||||
- Cycles and EEVEE now share the `Cast Shadow` property.
|
||||
|
||||
## Multithreaded Shader Compilation
|
||||
There's a new `Max Shader Compilation Subprocesses` option in `Preferences > System > Memory & Limits` that allows using multiple subprocesses to speed-up shader compilation on Windows and Linux.
|
||||
|
||||
## Platform compatibility
|
||||
|
||||
There are some platforms that are currently not working as expected at the initial release. Improvements to hardware support will become available in future updates.
|
||||
|
||||
- Apple Intel iGPU can leave red spots when ray tracing is enabled. [blender/blender#122361]
|
||||
- Windows on Intel HD 5000 series of GPU doesn't render dithered materials [blender/blender#122837]
|
||||
- Linux Mesa AMD RX 7000 series crashes after rendering when motion blur is enabled [blender/blender#124044]
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user