Cleanup: comments (long lines) in compositor
This commit is contained in:
parent
1e8697cd80
commit
163fb251b9
|
@ -26,6 +26,8 @@ extern "C" {
|
|||
#include "DNA_color_types.h"
|
||||
#include "DNA_node_types.h"
|
||||
|
||||
/* Keep ascii art. */
|
||||
/* clang-format off */
|
||||
/**
|
||||
* \defgroup Model The data model of the compositor
|
||||
* \defgroup Memory The memory management stuff
|
||||
|
@ -37,7 +39,8 @@ extern "C" {
|
|||
* \page Introduction of the Blender Compositor
|
||||
*
|
||||
* \section bcomp Blender compositor
|
||||
* This project redesigns the internals of Blender's compositor. The project has been executed in 2011 by At Mind.
|
||||
* This project redesigns the internals of Blender's compositor.
|
||||
* The project has been executed in 2011 by At Mind.
|
||||
* At Mind is a technology company located in Amsterdam, The Netherlands.
|
||||
* The project has been crowd-funded. This code has been released under GPL2 to be used in Blender.
|
||||
*
|
||||
|
@ -47,21 +50,24 @@ extern "C" {
|
|||
* - Make the compositor work faster for you (workflow)
|
||||
*
|
||||
* \section speed Faster compositor
|
||||
* The speedup has been done by making better use of the hardware Blenders is working on. The previous compositor only
|
||||
* used a single threaded model to calculate a node. The only exception to this is the Defocus node.
|
||||
* The speedup has been done by making better use of the hardware Blenders is working on.
|
||||
* The previous compositor only used a single threaded model to calculate a node.
|
||||
* The only exception to this is the Defocus node.
|
||||
* Only when it is possible to calculate two full nodes in parallel a second thread was used.
|
||||
* Current workstations have 8-16 threads available, and most of the time these are idle.
|
||||
*
|
||||
* In the new compositor we want to use as much of threads as possible. Even new OpenCL capable GPU-hardware can be
|
||||
* used for calculation.
|
||||
* In the new compositor we want to use as much of threads as possible.
|
||||
* Even new OpenCL capable GPU-hardware can be used for calculation.
|
||||
*
|
||||
* \section workflow Work faster
|
||||
* The previous compositor only showed the final image. The compositor could wait a long time before seeing the result
|
||||
* of his work. The new compositor will work in a way that it will focus on getting information back to the user.
|
||||
* It will prioritize its work to get earlier user feedback.
|
||||
* The previous compositor only showed the final image.
|
||||
* The compositor could wait a long time before seeing the result of his work.
|
||||
* The new compositor will work in a way that it will focus on
|
||||
* getting information back to the user. It will prioritize its work to get earlier user feedback.
|
||||
*
|
||||
* \page memory Memory model
|
||||
* The main issue is the type of memory model to use. Blender is used by consumers and professionals.
|
||||
* The main issue is the type of memory model to use.
|
||||
* Blender is used by consumers and professionals.
|
||||
* Ranging from low-end machines to very high-end machines.
|
||||
* The system should work on high-end machines and on low-end machines.
|
||||
* \page executing Executing
|
||||
|
@ -74,11 +80,15 @@ extern "C" {
|
|||
* this all is controlled from \see ExecutionSystem.execute
|
||||
*
|
||||
* \section priority Render priority
|
||||
* Render priority is an priority of an output node. A user has a different need of Render priorities of output nodes
|
||||
* Render priority is an priority of an output node.
|
||||
* A user has a different need of Render priorities of output nodes
|
||||
* than during editing.
|
||||
* for example. the Active ViewerNode has top priority during editing, but during rendering a CompositeNode has.
|
||||
* All NodeOperation has a setting for their render-priority, but only for output NodeOperation these have effect.
|
||||
* In ExecutionSystem.execute all priorities are checked. For every priority the ExecutionGroup's are check if the
|
||||
* for example. the Active ViewerNode has top priority during editing,
|
||||
* but during rendering a CompositeNode has.
|
||||
* All NodeOperation has a setting for their render-priority,
|
||||
* but only for output NodeOperation these have effect.
|
||||
* In ExecutionSystem.execute all priorities are checked.
|
||||
* For every priority the ExecutionGroup's are check if the
|
||||
* priority do match.
|
||||
* When match the ExecutionGroup will be executed (this happens in serial)
|
||||
*
|
||||
|
@ -89,27 +99,35 @@ extern "C" {
|
|||
* \section order Chunk order
|
||||
*
|
||||
* When a ExecutionGroup is executed, first the order of chunks are determined.
|
||||
* The settings are stored in the ViewerNode inside the ExecutionGroup. ExecutionGroups that have no viewer-node,
|
||||
* The settings are stored in the ViewerNode inside the ExecutionGroup.
|
||||
* ExecutionGroups that have no viewer-node,
|
||||
* will use a default one.
|
||||
* There are several possible chunk orders
|
||||
* - [@ref OrderOfChunks.COM_TO_CENTER_OUT]: Start calculating from a configurable point and order by nearest chunk
|
||||
* - [@ref OrderOfChunks.COM_TO_RANDOM]: Randomize all chunks.
|
||||
* - [@ref OrderOfChunks.COM_TO_TOP_DOWN]: Start calculation from the bottom to the top of the image
|
||||
* - [@ref OrderOfChunks.COM_TO_RULE_OF_THIRDS]: Experimental order based on 9 hot-spots in the image
|
||||
* - [@ref OrderOfChunks.COM_TO_CENTER_OUT]:
|
||||
* Start calculating from a configurable point and order by nearest chunk.
|
||||
* - [@ref OrderOfChunks.COM_TO_RANDOM]:
|
||||
* Randomize all chunks.
|
||||
* - [@ref OrderOfChunks.COM_TO_TOP_DOWN]:
|
||||
* Start calculation from the bottom to the top of the image.
|
||||
* - [@ref OrderOfChunks.COM_TO_RULE_OF_THIRDS]:
|
||||
* Experimental order based on 9 hot-spots in the image.
|
||||
*
|
||||
* When the chunk-order is determined, the first few chunks will be checked if they can be scheduled.
|
||||
* Chunks can have three states:
|
||||
* - [@ref ChunkExecutionState.COM_ES_NOT_SCHEDULED]: Chunk is not yet scheduled, or dependencies are not met
|
||||
* - [@ref ChunkExecutionState.COM_ES_SCHEDULED]: All dependencies are met, chunk is scheduled, but not finished
|
||||
* - [@ref ChunkExecutionState.COM_ES_EXECUTED]: Chunk is finished
|
||||
* - [@ref ChunkExecutionState.COM_ES_NOT_SCHEDULED]:
|
||||
* Chunk is not yet scheduled, or dependencies are not met.
|
||||
* - [@ref ChunkExecutionState.COM_ES_SCHEDULED]:
|
||||
* All dependencies are met, chunk is scheduled, but not finished.
|
||||
* - [@ref ChunkExecutionState.COM_ES_EXECUTED]:
|
||||
* Chunk is finished.
|
||||
*
|
||||
* \see ExecutionGroup.execute
|
||||
* \see ViewerOperation.getChunkOrder
|
||||
* \see OrderOfChunks
|
||||
*
|
||||
* \section interest Area of interest
|
||||
* An ExecutionGroup can have dependencies to other ExecutionGroup's. Data passing from one ExecutionGroup to another
|
||||
* one are stored in 'chunks'.
|
||||
* An ExecutionGroup can have dependencies to other ExecutionGroup's.
|
||||
* Data passing from one ExecutionGroup to another one are stored in 'chunks'.
|
||||
* If not all input chunks are available the chunk execution will not be scheduled.
|
||||
* <pre>
|
||||
* +-------------------------------------+ +--------------------------------------+
|
||||
|
@ -133,10 +151,12 @@ extern "C" {
|
|||
* +---------------------------+
|
||||
* </pre>
|
||||
*
|
||||
* In the above example ExecutionGroup B has an outputoperation (ViewerOperation) and is being executed.
|
||||
* In the above example ExecutionGroup B has an outputoperation (ViewerOperation)
|
||||
* and is being executed.
|
||||
* The first chunk is evaluated [@ref ExecutionGroup.scheduleChunkWhenPossible],
|
||||
* but not all input chunks are available. The relevant ExecutionGroup (that can calculate the missing chunks;
|
||||
* ExecutionGroup A) is asked to calculate the area ExecutionGroup B is missing.
|
||||
* but not all input chunks are available.
|
||||
* The relevant ExecutionGroup (that can calculate the missing chunks; ExecutionGroup A)
|
||||
* is asked to calculate the area ExecutionGroup B is missing.
|
||||
* [@ref ExecutionGroup.scheduleAreaWhenPossible]
|
||||
* ExecutionGroup B checks what chunks the area spans, and tries to schedule these chunks.
|
||||
* If all input data is available these chunks are scheduled [@ref ExecutionGroup.scheduleChunk]
|
||||
|
@ -200,47 +220,56 @@ extern "C" {
|
|||
*
|
||||
* </pre>
|
||||
*
|
||||
* \see ExecutionGroup.execute Execute a complete ExecutionGroup. Halts until finished or breaked by user
|
||||
* \see ExecutionGroup.execute Execute a complete ExecutionGroup.
|
||||
* Halts until finished or breaked by user
|
||||
* \see ExecutionGroup.scheduleChunkWhenPossible Tries to schedule a single chunk,
|
||||
* checks if all input data is available. Can trigger dependent chunks to be calculated
|
||||
* \see ExecutionGroup.scheduleAreaWhenPossible Tries to schedule an area. This can be multiple chunks
|
||||
* \see ExecutionGroup.scheduleAreaWhenPossible
|
||||
* Tries to schedule an area. This can be multiple chunks
|
||||
* (is called from [@ref ExecutionGroup.scheduleChunkWhenPossible])
|
||||
* \see ExecutionGroup.scheduleChunk Schedule a chunk on the WorkScheduler
|
||||
* \see NodeOperation.determineDependingAreaOfInterest Influence the area of interest of a chunk.
|
||||
* \see WriteBufferOperation Operation to write to a MemoryProxy/MemoryBuffer
|
||||
* \see ReadBufferOperation Operation to read from a MemoryProxy/MemoryBuffer
|
||||
* \see MemoryProxy proxy for information about memory image (a image consist out of multiple chunks)
|
||||
* \see MemoryProxy proxy for information about memory image
|
||||
* (a image consist out of multiple chunks)
|
||||
* \see MemoryBuffer Allocated memory for a single chunk
|
||||
*
|
||||
* \section workscheduler WorkScheduler
|
||||
* the WorkScheduler is implemented as a static class. the responsibility of the WorkScheduler is to balance
|
||||
* WorkPackages to the available and free devices.
|
||||
* the work-scheduler can work in 2 states. For witching these between the state you need to recompile blender
|
||||
* the WorkScheduler is implemented as a static class. the responsibility of the WorkScheduler
|
||||
* is to balance WorkPackages to the available and free devices.
|
||||
* the work-scheduler can work in 2 states.
|
||||
* For witching these between the state you need to recompile blender
|
||||
*
|
||||
* \subsection multithread Multi threaded
|
||||
* Default the work-scheduler will place all work as WorkPackage in a queue.
|
||||
* For every CPUcore a working thread is created. These working threads will ask the WorkScheduler if there is work
|
||||
* For every CPUcore a working thread is created.
|
||||
* These working threads will ask the WorkScheduler if there is work
|
||||
* for a specific Device.
|
||||
* the work-scheduler will find work for the device and the device will be asked to execute the WorkPackage
|
||||
* the work-scheduler will find work for the device and the device
|
||||
* will be asked to execute the WorkPackage.
|
||||
*
|
||||
* \subsection singlethread Single threaded
|
||||
* For debugging reasons the multi-threading can be disabled. This is done by changing the COM_CURRENT_THREADING_MODEL
|
||||
* For debugging reasons the multi-threading can be disabled.
|
||||
* This is done by changing the COM_CURRENT_THREADING_MODEL
|
||||
* to COM_TM_NOTHREAD. When compiling the work-scheduler
|
||||
* will be changes to support no threading and run everything on the CPU.
|
||||
*
|
||||
* \section devices Devices
|
||||
* A Device within the compositor context is a Hardware component that can used to calculate chunks.
|
||||
* This chunk is encapsulated in a WorkPackage.
|
||||
* the WorkScheduler controls the devices and selects the device where a WorkPackage will be calculated.
|
||||
* the WorkScheduler controls the devices and selects the device where a
|
||||
* WorkPackage will be calculated.
|
||||
*
|
||||
* \subsection WS_Devices Workscheduler
|
||||
* The WorkScheduler controls all Devices. When initializing the compositor the WorkScheduler selects
|
||||
* all devices that will be used during compositor.
|
||||
* The WorkScheduler controls all Devices.
|
||||
* When initializing the compositor the WorkScheduler selects all
|
||||
* devices that will be used during compositor.
|
||||
* There are two types of Devices, CPUDevice and OpenCLDevice.
|
||||
* When an ExecutionGroup schedules a Chunk the schedule method of the WorkScheduler
|
||||
* The Workscheduler determines if the chunk can be run on an OpenCLDevice
|
||||
* (and that there are available OpenCLDevice). If this is the case the chunk will be added to the worklist for
|
||||
* OpenCLDevice's
|
||||
* (and that there are available OpenCLDevice).
|
||||
* If this is the case the chunk will be added to the worklist for OpenCLDevice's
|
||||
* otherwise the chunk will be added to the worklist of CPUDevices.
|
||||
*
|
||||
* A thread will read the work-list and sends a workpackage to its device.
|
||||
|
@ -249,8 +278,8 @@ extern "C" {
|
|||
* \see Device.execute method called to execute a chunk
|
||||
*
|
||||
* \subsection CPUDevice CPUDevice
|
||||
* When a CPUDevice gets a WorkPackage the Device will get the inputbuffer that is needed to calculate the chunk.
|
||||
* Allocation is already done by the ExecutionGroup.
|
||||
* When a CPUDevice gets a WorkPackage the Device will get the inputbuffer that is needed to
|
||||
* calculate the chunk. Allocation is already done by the ExecutionGroup.
|
||||
* The outputbuffer of the chunk is being created.
|
||||
* The OutputOperation of the ExecutionGroup is called to execute the area of the outputbuffer.
|
||||
*
|
||||
|
@ -282,7 +311,8 @@ extern "C" {
|
|||
* reference to the compositor editing tree
|
||||
*
|
||||
* \param rendering: [true false]
|
||||
* This parameter determines whether the function is called from rendering (true) or editing (false).
|
||||
* This parameter determines whether the function is called from rendering
|
||||
* (true) or editing (false).
|
||||
* based on this setting the system will work differently:
|
||||
* - during rendering only Composite & the File output node will be calculated
|
||||
* \see NodeOperation.isOutputProgram(int rendering) of the specific operations
|
||||
|
@ -290,7 +320,8 @@ extern "C" {
|
|||
* - during editing all output nodes will be calculated
|
||||
* \see NodeOperation.isOutputProgram(int rendering) of the specific operations
|
||||
*
|
||||
* - another quality setting can be used bNodeTree. The quality is determined by the bNodeTree fields.
|
||||
* - another quality setting can be used bNodeTree.
|
||||
* The quality is determined by the bNodeTree fields.
|
||||
* quality can be modified by the user from within the node panels.
|
||||
* \see bNodeTree.edit_quality
|
||||
* \see bNodeTree.render_quality
|
||||
|
@ -309,6 +340,8 @@ extern "C" {
|
|||
* should be checked further, probably it'll be also needed for preview
|
||||
* generation in display space
|
||||
*/
|
||||
/* clang-format off */
|
||||
|
||||
void COM_execute(RenderData *rd,
|
||||
Scene *scene,
|
||||
bNodeTree *editingtree,
|
||||
|
|
Loading…
Reference in New Issue