Cleanup: comment line length (editors)
[blender.git] / source / blender / compositor / COM_compositor.h
1 /*
2  * Copyright 2011, Blender Foundation.
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * Contributor:
19  *      Jeroen Bakker
20  *      Monique Dewanchand
21  */
22
23 #ifndef __COM_COMPOSITOR_H__
24 #define __COM_COMPOSITOR_H__
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 #include "DNA_color_types.h"
31 #include "DNA_node_types.h"
32
33 /**
34  * \defgroup Model The data model of the compositor
35  * \defgroup Memory The memory management stuff
36  * \defgroup Execution The execution logic
37  * \defgroup Conversion Conversion logic
38  * \defgroup Node All nodes of the compositor
39  * \defgroup Operation All operations of the compositor
40  *
41  * \page Introduction of the Blender Compositor
42  *
43  * \section bcomp Blender compositor
44  * This project redesigns the internals of Blender's compositor. The project has been executed in 2011 by At Mind.
45  * At Mind is a technology company located in Amsterdam, The Netherlands.
46  * The project has been crowd-funded. This code has been released under GPL2 to be used in Blender.
47  *
48  * \section goals The goals of the project
49  * the new compositor has 2 goals.
50  *   - Make a faster compositor (speed of calculation)
51  *   - Make the compositor work faster for you (workflow)
52  *
53  * \section speed Faster compositor
54  * The speedup has been done by making better use of the hardware Blenders is working on. The previous compositor only
55  * used a single threaded model to calculate a node. The only exception to this is the Defocus node.
56  * Only when it is possible to calculate two full nodes in parallel a second thread was used.
57  * Current workstations have 8-16 threads available, and most of the time these are idle.
58  *
59  * In the new compositor we want to use as much of threads as possible. Even new OpenCL capable GPU-hardware can be
60  * used for calculation.
61  *
62  * \section workflow Work faster
63  * The previous compositor only showed the final image. The compositor could wait a long time before seeing the result
64  * of his work. The new compositor will work in a way that it will focus on getting information back to the user.
65  * It will prioritize its work to get earlier user feedback.
66  *
67  * \page memory Memory model
68  * The main issue is the type of memory model to use. Blender is used by consumers and professionals.
69  * Ranging from low-end machines to very high-end machines.
70  * The system should work on high-end machines and on low-end machines.
71  *
72  *
73  * \page executing Executing
74  * \section prepare Prepare execution
75  *
76  * during the preparation of the execution All ReadBufferOperation will receive an offset.
77  * This offset is used during execution as an optimization trick
78  * Next all operations will be initialized for execution \see NodeOperation.initExecution
79  * Next all ExecutionGroup's will be initialized for execution \see ExecutionGroup.initExecution
80  * this all is controlled from \see ExecutionSystem.execute
81  *
82  * \section priority Render priority
83  * Render priority is an priority of an output node. A user has a different need of Render priorities of output nodes
84  * than during editing.
85  * for example. the Active ViewerNode has top priority during editing, but during rendering a CompositeNode has.
86  * All NodeOperation has a setting for their render-priority, but only for output NodeOperation these have effect.
87  * In ExecutionSystem.execute all priorities are checked. For every priority the ExecutionGroup's are check if the
88  * priority do match.
89  * When match the ExecutionGroup will be executed (this happens in serial)
90  *
91  * \see ExecutionSystem.execute control of the Render priority
92  * \see NodeOperation.getRenderPriority receive the render priority
93  * \see ExecutionGroup.execute the main loop to execute a whole ExecutionGroup
94  *
95  * \section order Chunk order
96  *
97  * When a ExecutionGroup is executed, first the order of chunks are determined.
98  * The settings are stored in the ViewerNode inside the ExecutionGroup. ExecutionGroups that have no viewer-node,
99  * will use a default one.
100  * There are several possible chunk orders
101  *  - [@ref OrderOfChunks.COM_TO_CENTER_OUT]: Start calculating from a configurable point and order by nearest chunk
102  *  - [@ref OrderOfChunks.COM_TO_RANDOM]: Randomize all chunks.
103  *  - [@ref OrderOfChunks.COM_TO_TOP_DOWN]: Start calculation from the bottom to the top of the image
104  *  - [@ref OrderOfChunks.COM_TO_RULE_OF_THIRDS]: Experimental order based on 9 hot-spots in the image
105  *
106  * When the chunk-order is determined, the first few chunks will be checked if they can be scheduled.
107  * Chunks can have three states:
108  *  - [@ref ChunkExecutionState.COM_ES_NOT_SCHEDULED]: Chunk is not yet scheduled, or dependencies are not met
109  *  - [@ref ChunkExecutionState.COM_ES_SCHEDULED]: All dependencies are met, chunk is scheduled, but not finished
110  *  - [@ref ChunkExecutionState.COM_ES_EXECUTED]: Chunk is finished
111  *
112  * \see ExecutionGroup.execute
113  * \see ViewerOperation.getChunkOrder
114  * \see OrderOfChunks
115  *
116  * \section interest Area of interest
117  * An ExecutionGroup can have dependencies to other ExecutionGroup's. Data passing from one ExecutionGroup to another
118  * one are stored in 'chunks'.
119  * If not all input chunks are available the chunk execution will not be scheduled.
120  * <pre>
121  * +-------------------------------------+              +--------------------------------------+
122  * | ExecutionGroup A                    |              | ExecutionGroup B                     |
123  * | +----------------+  +-------------+ |              | +------------+   +-----------------+ |
124  * | | NodeOperation a|  | WriteBuffer | |              | | ReadBuffer |   | ViewerOperation | |
125  * | |                *==* Operation   | |              | | Operation  *===*                 | |
126  * | |                |  |             | |              | |            |   |                 | |
127  * | +----------------+  +-------------+ |              | +------------+   +-----------------+ |
128  * |                                |    |              |   |                                  |
129  * +--------------------------------|----+              +---|----------------------------------+
130  *                                  |                       |
131  *                                  |                       |
132  *                                +---------------------------+
133  *                                | MemoryProxy               |
134  *                                | +----------+  +---------+ |
135  *                                | | Chunk a  |  | Chunk b | |
136  *                                | |          |  |         | |
137  *                                | +----------+  +---------+ |
138  *                                |                           |
139  *                                +---------------------------+
140  * </pre>
141  *
142  * In the above example ExecutionGroup B has an outputoperation (ViewerOperation) and is being executed.
143  * The first chunk is evaluated [@ref ExecutionGroup.scheduleChunkWhenPossible],
144  * but not all input chunks are available. The relevant ExecutionGroup (that can calculate the missing chunks;
145  * ExecutionGroup A) is asked to calculate the area ExecutionGroup B is missing.
146  * [@ref ExecutionGroup.scheduleAreaWhenPossible]
147  * ExecutionGroup B checks what chunks the area spans, and tries to schedule these chunks.
148  * If all input data is available these chunks are scheduled [@ref ExecutionGroup.scheduleChunk]
149  *
150  * <pre>
151  *
152  * +-------------------------+        +----------------+                           +----------------+
153  * | ExecutionSystem.execute |        | ExecutionGroup |                           | ExecutionGroup |
154  * +-------------------------+        | (B)            |                           | (A)            |
155  *            O                       +----------------+                           +----------------+
156  *            O                                |                                            |
157  *            O       ExecutionGroup.execute   |                                            |
158  *            O------------------------------->O                                            |
159  *            .                                O                                            |
160  *            .                                O-------\                                    |
161  *            .                                .       | ExecutionGroup.scheduleChunkWhenPossible
162  *            .                                .  O----/ (*)                                |
163  *            .                                .  O                                         |
164  *            .                                .  O                                         |
165  *            .                                .  O  ExecutionGroup.scheduleAreaWhenPossible|
166  *            .                                .  O---------------------------------------->O
167  *            .                                .  .                                         O----------\ ExecutionGroup.scheduleChunkWhenPossible
168  *            .                                .  .                                         .          | (*)
169  *            .                                .  .                                         .  O-------/
170  *            .                                .  .                                         .  O
171  *            .                                .  .                                         .  O
172  *            .                                .  .                                         .  O-------\ ExecutionGroup.scheduleChunk
173  *            .                                .  .                                         .  .       |
174  *            .                                .  .                                         .  .  O----/
175  *            .                                .  .                                         .  O<=O
176  *            .                                .  .                                         O<=O
177  *            .                                .  .                                         O
178  *            .                                .  O<========================================O
179  *            .                                .  O                                         |
180  *            .                                O<=O                                         |
181  *            .                                O                                            |
182  *            .                                O                                            |
183  * </pre>
184  *
185  * This happens until all chunks of (ExecutionGroup B) are finished executing or the user break's the process.
186  *
187  * NodeOperation like the ScaleOperation can influence the area of interest by reimplementing the
188  * [@ref NodeOperation.determineAreaOfInterest] method
189  *
190  * <pre>
191  *
192  * +--------------------------+                             +---------------------------------+
193  * | ExecutionGroup A         |                             | ExecutionGroup B                |
194  * |                          |                             |                                 |
195  * +--------------------------+                             +---------------------------------+
196  *           Needed chunks from ExecutionGroup A               |   Chunk of ExecutionGroup B (to be evaluated)
197  *            +-------+ +-------+                              |                  +--------+
198  *            |Chunk 1| |Chunk 2|               +----------------+                |Chunk 1 |
199  *            |       | |       |               | ScaleOperation |                |        |
200  *            +-------+ +-------+               +----------------+                +--------+
201  *
202  *            +-------+ +-------+
203  *            |Chunk 3| |Chunk 4|
204  *            |       | |       |
205  *            +-------+ +-------+
206  *
207  * </pre>
208  *
209  * \see ExecutionGroup.execute Execute a complete ExecutionGroup. Halts until finished or breaked by user
210  * \see ExecutionGroup.scheduleChunkWhenPossible Tries to schedule a single chunk,
211  * checks if all input data is available. Can trigger dependent chunks to be calculated
212  * \see ExecutionGroup.scheduleAreaWhenPossible Tries to schedule an area. This can be multiple chunks
213  * (is called from [@ref ExecutionGroup.scheduleChunkWhenPossible])
214  * \see ExecutionGroup.scheduleChunk Schedule a chunk on the WorkScheduler
215  * \see NodeOperation.determineDependingAreaOfInterest Influence the area of interest of a chunk.
216  * \see WriteBufferOperation Operation to write to a MemoryProxy/MemoryBuffer
217  * \see ReadBufferOperation Operation to read from a MemoryProxy/MemoryBuffer
218  * \see MemoryProxy proxy for information about memory image (a image consist out of multiple chunks)
219  * \see MemoryBuffer Allocated memory for a single chunk
220  *
221  * \section workscheduler WorkScheduler
222  * the WorkScheduler is implemented as a static class. the responsibility of the WorkScheduler is to balance
223  * WorkPackages to the available and free devices.
224  * the work-scheduler can work in 2 states. For witching these between the state you need to recompile blender
225  *
226  * \subsection multithread Multi threaded
227  * Default the work-scheduler will place all work as WorkPackage in a queue.
228  * For every CPUcore a working thread is created. These working threads will ask the WorkScheduler if there is work
229  * for a specific Device.
230  * the work-scheduler will find work for the device and the device will be asked to execute the WorkPackage
231  *
232  * \subsection singlethread Single threaded
233  * For debugging reasons the multi-threading can be disabled. This is done by changing the COM_CURRENT_THREADING_MODEL
234  * to COM_TM_NOTHREAD. When compiling the work-scheduler
235  * will be changes to support no threading and run everything on the CPU.
236  *
237  * \section devices Devices
238  * A Device within the compositor context is a Hardware component that can used to calculate chunks.
239  * This chunk is encapsulated in a WorkPackage.
240  * the WorkScheduler controls the devices and selects the device where a WorkPackage will be calculated.
241  *
242  * \subsection WS_Devices Workscheduler
243  * The WorkScheduler controls all Devices. When initializing the compositor the WorkScheduler selects
244  * all devices that will be used during compositor.
245  * There are two types of Devices, CPUDevice and OpenCLDevice.
246  * When an ExecutionGroup schedules a Chunk the schedule method of the WorkScheduler
247  * The Workscheduler determines if the chunk can be run on an OpenCLDevice
248  * (and that there are available OpenCLDevice). If this is the case the chunk will be added to the worklist for
249  * OpenCLDevice's
250  * otherwise the chunk will be added to the worklist of CPUDevices.
251  *
252  * A thread will read the work-list and sends a workpackage to its device.
253  *
254  * \see WorkScheduler.schedule method that is called to schedule a chunk
255  * \see Device.execute method called to execute a chunk
256  *
257  * \subsection CPUDevice CPUDevice
258  * When a CPUDevice gets a WorkPackage the Device will get the inputbuffer that is needed to calculate the chunk.
259  * Allocation is already done by the ExecutionGroup.
260  * The outputbuffer of the chunk is being created.
261  * The OutputOperation of the ExecutionGroup is called to execute the area of the outputbuffer.
262  *
263  * \see ExecutionGroup
264  * \see NodeOperation.executeRegion executes a single chunk of a NodeOperation
265  * \see CPUDevice.execute
266  *
267  * \subsection GPUDevice OpenCLDevice
268  *
269  * To be completed!
270  * \see NodeOperation.executeOpenCLRegion
271  * \see OpenCLDevice.execute
272  *
273  * \section executePixel executing a pixel
274  * Finally the last step, the node functionality :)
275  *
276  * \page newnode Creating new nodes
277  */
278
279 /**
280  * \brief The main method that is used to execute the compositor tree.
281  * It can be executed during editing (blenkernel/node.c) or rendering
282  * (renderer/pipeline.c)
283  *
284  * \param rd: [struct RenderData]
285  *   Render data for this composite, this won't always belong to a scene.
286  *
287  * \param editingtree: [struct bNodeTree]
288  *   reference to the compositor editing tree
289  *
290  * \param rendering: [true false]
291  *    This parameter determines whether the function is called from rendering (true) or editing (false).
292  *    based on this setting the system will work differently:
293  *     - during rendering only Composite & the File output node will be calculated
294  * \see NodeOperation.isOutputProgram(int rendering) of the specific operations
295  *
296  *     - during editing all output nodes will be calculated
297  * \see NodeOperation.isOutputProgram(int rendering) of the specific operations
298  *
299  *     - another quality setting can be used bNodeTree. The quality is determined by the bNodeTree fields.
300  *       quality can be modified by the user from within the node panels.
301  * \see bNodeTree.edit_quality
302  * \see bNodeTree.render_quality
303  *
304  *     - output nodes can have different priorities in the WorkScheduler.
305  * This is implemented in the COM_execute function.
306  *
307  * \param viewSettings:
308  *   reference to view settings used for color management
309  *
310  * \param displaySettings:
311  *   reference to display settings used for color management
312  *
313  * OCIO_TODO: this options only used in rare cases, namely in output file node,
314  *            so probably this settings could be passed in a nicer way.
315  *            should be checked further, probably it'll be also needed for preview
316  *            generation in display space
317  */
318 void COM_execute(RenderData *rd, Scene *scene, bNodeTree *editingtree, int rendering,
319                  const ColorManagedViewSettings *viewSettings, const ColorManagedDisplaySettings *displaySettings,
320                  const char *viewName);
321
322 /**
323  * \brief Deinitialize the compositor caches and allocated memory.
324  * Use COM_clearCaches to only free the caches.
325  */
326 void COM_deinitialize(void);
327
328 /**
329  * \brief Clear all compositor caches. (Compositor system will still remain available).
330  * To deinitialize the compositor use the COM_deinitialize method.
331  */
332 // void COM_clearCaches(void); // NOT YET WRITTEN
333
334 #ifdef __cplusplus
335 }
336 #endif
337
338 #endif  /* __COM_COMPOSITOR_H__ */