[Bf-docboard-svn] bf-manual: [9832] trunk/blender_docs/manual: Document realtime compositor
Omar Emara
noreply at blender.org
Thu Dec 29 15:29:05 CET 2022
Revision: 9832
https://developer.blender.org/rBM9832
Author: OmarSquircleArt
Date: 2022-12-29 15:29:04 +0100 (Thu, 29 Dec 2022)
Log Message:
-----------
Document realtime compositor
This patch documents the realtime compositor and establishes a link to
the viewport compositor.
Modified Paths:
--------------
trunk/blender_docs/manual/compositing/index.rst
trunk/blender_docs/manual/editors/3dview/display/shading.rst
Added Paths:
-----------
trunk/blender_docs/manual/compositing/realtime_compositor.rst
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_data_type_implicit_conversion.png
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_image-domain_example.png
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_operation-domain_considerations_clipping-solution.png
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_operation-domain_considerations_clipping.png
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_operation-domain_considerations_pixelation.png
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_operation-domain_example.png
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_operation-domain_real-example.png
trunk/blender_docs/manual/images/compositing_realtime-compositor_compositing-space_operation-domain_wrapping.png
Modified: trunk/blender_docs/manual/compositing/index.rst
===================================================================
--- trunk/blender_docs/manual/compositing/index.rst 2022-12-23 23:39:14 UTC (rev 9831)
+++ trunk/blender_docs/manual/compositing/index.rst 2022-12-29 14:29:04 UTC (rev 9832)
@@ -10,9 +10,12 @@
introduction.rst
sidebar.rst
+ realtime_compositor.rst
.. index:: Compositor Nodes
+.. _compositor-nodes:
+
Node Types
==========
Added: trunk/blender_docs/manual/compositing/realtime_compositor.rst
===================================================================
--- trunk/blender_docs/manual/compositing/realtime_compositor.rst (rev 0)
+++ trunk/blender_docs/manual/compositing/realtime_compositor.rst 2022-12-29 14:29:04 UTC (rev 9832)
@@ -0,0 +1,317 @@
+.. _realtime-compositor:
+
+*******************
+Realtime Compositor
+*******************
+
+The Realtime Compositor is a new GPU accelerated compositor introduced in Blender 3.5 and is
+currently used for :ref:`viewport compositing <viewport-compositing>`. This compositor is currently
+more limited and not all :ref:`Compositor Nodes <compositor-nodes>` are supported, such nodes are
+marked with the :guilabel:`CPU Compositor Only` label along with notes about other limitations.
+Moreover, MacOS is not supported due to missing support for modern OpenGL.
+
+Data
+====
+
+Dimensionality
+--------------
+
+Compositing nodes operate on data that is either an image or a dimensionless single value. For
+instance, the :ref:`Levels node <bpy.types.CompositorNodeLevels>` outputs a single value, while the
+:ref:`Render Layers node <bpy.types.CompositorNodeRLayers>` outputs an image. Node inputs that
+expect a single value assume a default value if an image is given and ignore the image completely,
+for instance, the :ref:`Transform node <bpy.types.CompositorNodeTransform>` expects single values
+for its inputs and will assume default values if images were given to those inputs. The default
+values are those that are considered identity and thus have no effect on the output, so for the
+:ref:`Transform node <bpy.types.CompositorNodeTransform>`, the *X*, *Y*, and *Angle* inputs will
+have a default value of zero, while the *Scale* input will have a default value of one. On the other
+hand, if node inputs that expect an image are given a single value, the single value will be assumed
+to cover the whole compositing space. For instance, the :ref:`Filter node
+<bpy.types.CompositorNodeFilter>` expect its *Factor* input to be an image, but if a single value is
+given, it will be assumed to be the same for all pixels.
+
+Type
+----
+
+Three types of data exist, all of which are stored in half precision formats:
+
+Float
+ A signed floating-point number. Integer data is also stored as floats because no integer type
+ exist.
+
+Vector
+ A 4D vector. While it is 4D, it can have different interpretations depending on the node that uses
+ it. It can be treated as a 2D vector with the last two components ignored, for instance, the
+ *Vector* input of the :ref:`Displace node <bpy.types.CompositorNodeDisplace>` is treated as a 2D
+ vector. It can be treated as a 3D vector with the last component ignored, for instance, the
+ *Vector* input of the :ref:`Seperate XYZ node <bpy.types.CompositorNodeSeparateXYZ>` is treated as
+ a 3D vector. It can be treated as two consecutive 2D vectors. For instance the *Velocity Pass* as
+ expected by the :ref:`Vector Blur node <bpy.types.CompositorNodeVecBlur>` is assumed to have the
+ *2D Previous Velocity* in the X and Y components of the vector and the *2D Next Velocity* in the
+ Z and W components of the vector.
+
+Color
+ A 4D vector storing the Red, Green, Blue, and Alpha of the color. The color is free form and does
+ not conform to a specific color space or alpha storage model, instead, appropriate nodes will have
+ settings to control the representation of their output and nodes exist to convert between the
+ different representations.
+
+Implicit Conversion
+^^^^^^^^^^^^^^^^^^^
+
+In case a node input is given data of type other than its own type, the following implicit
+conversions are performed:
+
++---------+---------+-------------------------------------+
+| Source | Target | Conversion |
++=========+=========+=====================================+
+| Float | Vector | f => Vector(f, f, f, 0) |
++---------+---------+-------------------------------------+
+| Float | Color | f => Color(f, f, f, 1) |
++---------+---------+-------------------------------------+
+| Vector | Float | (x, y, z, w) => Average(x, y, z) |
++---------+---------+-------------------------------------+
+| Vector | Color | (x, y, z, w) => Color(x, y, z, 1) |
++---------+---------+-------------------------------------+
+| Color | Float | (r, g, b, a) => Average(r, g, b) |
++---------+---------+-------------------------------------+
+| Color | Vector | (r, g, b, a) => Vector(r, g, b, 0) |
++---------+---------+-------------------------------------+
+
+The following example demonstrates implicit conversion between a color type and a float type, since
+the :ref:`Math node <bpy.types.CompositorNodeMath>` expect float inputs.
+
+.. figure:: /images/compositing_realtime-compositor_compositing-space_data_type_implicit_conversion.png
+
+ An example that demonstrates implicit conversion between a color type and a float type, since the
+ *Math* node expects float inputs.
+
+Compositing Space
+=================
+
+Image Domain
+------------
+
+The compositor is designed in such a way as to allow compositing in an infinite compositing space.
+Consequently, images are not only represented by their size, but also by their transformation in
+that space, much like 3D objects have transformations. An identity transformation represents an
+image that is centered in space. The rectangular area occupied by an image in that space as defined
+by its transformation and size is called the *Domain* of the image. The figure below demonstrates
+the domains of two example images.
+
+..
+ \documentclass[tikz, convert]{standalone}
+ \begin{document}
+ \begin{tikzpicture}
+ % Draw axis and grid.
+ \draw[help lines, color = gray, dashed] (-4.9,-3.9) grid (4.9,3.9);
+ \draw[->, thick] (-5,0) -- (5,0) node[right] {$x$};
+ \draw[->, thick] (0,-4) -- (0,4) node[above] {$y$};
+ % Draw bigger domain.
+ \draw[ultra thick] (-4, -3) rectangle (4, 3);
+ \node[above] at (-2, 3) {800px $\times$ 600px};
+ % Draw smaller domain.
+ \draw[ultra thick] (1, 1) rectangle (3, 2);
+ \node[above] at (2, 2) {800px $\times$ 400px};
+ \end{tikzpicture}
+ \end{document}
+
+.. figure:: /images/compositing_realtime-compositor_compositing-space_image-domain_example.png
+
+ The domains of two example images are illustrated on the compositing space. One of the images is
+ centered in space and the other is scaled down and translated such that it lies in the upper
+ right quadrant of the space. Notice that both images have similar sizes in pixels, yet their
+ apparent sizes are different.
+
+Images can be transformed using nodes like the :ref:`Transform <bpy.types.CompositorNodeTransform>`,
+:ref:`Translate <bpy.types.CompositorNodeTranslate>`, and :ref:`Rotate
+<bpy.types.CompositorNodeRotate>` nodes.
+
+Operation Domain
+----------------
+
+:ref:`Compositor Nodes <compositor-nodes>` operate on a specific rectangular area of the compositing
+space called the *Operation Domain*. The nodes only consider the area of the input images that
+overlap the operation domain and ignores the rest of the images. If an input image doesn't
+completely overlap the operation domain, the rest of the operation domain for that input will be
+assumed to be a zero value, a zero vector, or a transparent zero color depending on the type. This
+behavior can be changed to an extent, see the section about *Wrapping* below.
+
+For instance, the figure below illustrates a case where the operation domain of a node is the large
+blue area and the domain of an input image is the small red area. In that case, the input image
+doesn't completely overlap the operation domain, so the rest of the blue area for that input image
+is assumed to be zero.
+
+..
+ \documentclass[tikz, convert]{standalone}
+ \begin{document}
+ \begin{tikzpicture}
+ % Draw axis and grid.
+ \draw[help lines, color = gray, dashed] (-4.9,-3.9) grid (4.9,3.9);
+ \draw[->, thick] (-5,0) -- (5,0) node[right] {$x$};
+ \draw[->, thick] (0,-4) -- (0,4) node[above] {$y$};
+ % Draw operation domain.
+ \fill[opacity = 0.3, blue] (-4, -3) rectangle (4, 3);
+ \draw[ultra thick] (-4, -3) rectangle (4, 3);
+ % Draw input image domain.
+ \fill[fill opacity = 0.3, red] (0, 0) rectangle (3, 2);
+ \draw[ultra thick] (0, 0) rectangle (3, 2);
+ \end{tikzpicture}
+ \end{document}
+
+.. figure:: /images/compositing_realtime-compositor_compositing-space_operation-domain_example.png
+
+ An example case where the operation domain of a node is shown in blue and the domain of an input
+ image is shown in red. Since the input image doesn't completely cover the operation domain of the
+ node, the rest of the blue area for that input image is assumed to be zero.
+
+The previous illustration is a representation of a real world example where one uses the :ref:`Alpha
+Over <bpy.types.CompositorNodeAlphaOver>` node to overlay a small logo on an image, as shown in the
+figure below. In that case, the operation domain covers the entirety of the viewport---as will later
+be demonstrated, but the logo covers only a small area of it, so the rest of the area is assumed to
+be a zero transparent color, which is convenient for the use case.
+
+.. figure:: /images/compositing_realtime-compositor_compositing-space_operation-domain_real-example.png
+
+ A real world example where the Alpha Over node is used to over a small logo on an image. The logo
+ only covers a small area of the operation domain, which is the whole viewport in this case, so
+ the rest of the area is assumed to be a zero transparent color.
+
+Interpolation
+^^^^^^^^^^^^^
+
+If an input image to a node is not perfectly aligned with the operation domain of the node or have a
@@ Diff output truncated at 10240 characters. @@
More information about the Bf-docboard-svn
mailing list