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