Blender V5.3
COM_render_context.hh
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
5#pragma once
6
7#include <memory>
8#include <string>
9
10#include "BLI_map.hh"
12
13#include "DNA_scene_types.h"
14
15namespace blender {
16
17struct RenderResult;
18
19namespace compositor {
20
21class Result;
22
23/* ------------------------------------------------------------------------------------------------
24 * File Output
25 *
26 * A FileOutput represents an image that will be saved to a file output. The image is internally
27 * stored as a RenderResult and saved at the path according to the image format. The image can
28 * either be saved as an EXR image or a non-EXR image, specified by the format. This is important
29 * because EXR images needs to constructed differently from other image types as will be explained
30 * in the following sections.
31 *
32 * For EXR images, the render result needs to be composed of passes for each layer, so the add_pass
33 * method should be called to add each of the passes. Additionally, an empty view should be added
34 * for each of the views referenced by the passes, using the single-argument overload of the
35 * add_view method. Those views are merely empty structure and does not hold any data aside from
36 * the view name. An exception to this rule is stereo EXR images, which needs to have the same
37 * structure as non-EXR images as explained in the following section.
38 *
39 * For non-EXR images, the render result needs to composed of views, so the multi-argument overload
40 * of the method add_view should be used to add each view.
41 *
42 * Color management will be applied on the images if save_as_render_ is true.
43 *
44 * Meta data can be added using the add_meta_data function. */
46 private:
47 std::string path_;
48 ImageFormatData format_;
49 RenderResult *render_result_;
50 bool save_as_render_;
52
53 public:
54 /* Allocate and initialize the internal render result of the file output using the give
55 * parameters. See the implementation for more information. */
56 FileOutput(const std::string &path,
57 const ImageFormatData &format,
58 int2 size,
59 bool save_as_render);
60
61 /* Free the internal render result. */
63
64 /* Add an empty view with the given name. An empty view is just structure and does not hold any
65 * data aside from the view name. This should be called for each view referenced by passes. This
66 * should only be called for EXR images. */
67 void add_view(const char *view_name);
68
69 /* Add a view of the given name that stores the given result data. */
70 void add_view(const char *view_name, const Result &data);
71
72 /* Add a pass of the given name in the given view that stores the given result data composed of
73 * each of the channels given by the channels string. The channels string should contain a
74 * character for each channel in the pixel buffer representing the channel ID. This should only
75 * be called for EXR images. The given view name should be the name of an added view using the
76 * add_view method. */
77 void add_pass(const char *pass_name,
78 const char *view_name,
79 const char *channels,
80 const Result &data);
81
82 /* Add meta data that will eventually be saved to the file if the format supports it. */
83 void add_meta_data(std::string key, std::string value);
84
85 /* Save the file to the path along with its meta data, reporting any reports to the standard
86 * output. */
87 void save(Scene *scene);
88};
89
90/* ------------------------------------------------------------------------------------------------
91 * Render Context
92 *
93 * A render context is created by the render pipeline and passed to the compositor to stores data
94 * that is specifically related to the rendering process. In particular, since the compositor is
95 * executed for each view separately and consecutively, it can be used to store and accumulate
96 * data from each of the evaluations of each view, for instance, to save all views in a single file
97 * for the File Output node, see the file_outputs_ member for more information. */
99 public:
100 /* True if the render context represents an animation render. */
102
103 private:
104 /* A mapping between file outputs and their image file paths. Those are constructed in the
105 * get_file_output method and saved in the save_file_outputs method. See those methods for more
106 * information. */
108
109 public:
110 /* Check if there is an available file output with the given path in the context, if one exists,
111 * return it, otherwise, return a newly created one from the given parameters and add it to the
112 * context. The arguments are ignored if the file output already exist. This method is typically
113 * called in the File Output nodes in the compositor.
114 *
115 * Since the compositor gets executed multiple times for each view, for single view renders, the
116 * file output will be constructed and fully initialized in the same compositor evaluation. For
117 * multi-view renders, the file output will be constructed in the evaluation of the first view,
118 * and each view will subsequently add its data until the file output is fully initialized in the
119 * last view. The render pipeline code will then call the save_file_outputs method after all
120 * views were evaluated to write the file outputs. */
121 FileOutput &get_file_output(std::string path,
122 ImageFormatData format,
123 int2 size,
124 bool save_as_render);
125
126 /* Write the file outputs that were added to the context. The render pipeline code should call
127 * this method after all views were evaluated to write the file outputs. See the get_file_output
128 * method for more information. */
129 void save_file_outputs(Scene *scene);
130};
131
132} // namespace compositor
133} // namespace blender
void add_view(const char *view_name)
FileOutput(const std::string &path, const ImageFormatData &format, int2 size, bool save_as_render)
void add_pass(const char *pass_name, const char *view_name, const char *channels, const Result &data)
void add_meta_data(std::string key, std::string value)
FileOutput & get_file_output(std::string path, ImageFormatData format, int2 size, bool save_as_render)
BMesh Iterators.
BMesh const char void * data