Cleanup: comments (long lines) in compositor

1 files changed, 77 insertions, 44 deletions

diff --git a/source/blender/compositor/COM_compositor.h b/source/blender/compositor/COM_compositor.h
index 9046a5e5dc3..55f68f2b5c1 100644
--- a/source/blender/compositor/COM_compositor.h
+++ b/source/blender/compositor/COM_compositor.h
@@ -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,