1
2//
3// This source file is part of appleseed.
4// Visit http://appleseedhq.net/ for additional information and resources.
5//
6// This software is released under the MIT license.
7//
8// Copyright (c) 2010-2013 Francois Beaune, Jupiter Jazz Limited
9// Copyright (c) 2014-2017 Francois Beaune, The appleseedhq Organization
10//
11// Permission is hereby granted, free of charge, to any person obtaining a copy
12// of this software and associated documentation files (the "Software"), to deal
13// in the Software without restriction, including without limitation the rights
14// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
15// copies of the Software, and to permit persons to whom the Software is
16// furnished to do so, subject to the following conditions:
17//
18// The above copyright notice and this permission notice shall be included in
19// all copies or substantial portions of the Software.
20//
21// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
22// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
23// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
24// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
25// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
26// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
27// THE SOFTWARE.
28//
29
30#ifndef APPLESEED_RENDERER_MODELING_FRAME_FRAME_H
31#define APPLESEED_RENDERER_MODELING_FRAME_FRAME_H
32
33// appleseed.renderer headers.
34#include "renderer/modeling/entity/entity.h"
35
36// appleseed.foundation headers.
37#include "foundation/image/canvasproperties.h"
38#include "foundation/image/colorspace.h"
39#include "foundation/math/aabb.h"
40#include "foundation/math/filter.h"
41#include "foundation/math/vector.h"
42#include "foundation/platform/compiler.h"
43#include "foundation/utility/autoreleaseptr.h"
44#include "foundation/utility/uid.h"
45
46// appleseed.main headers.
47#include "main/dllsymbol.h"
48
49// Standard headers.
50#include <cassert>
51#include <cstddef>
52
53// Forward declarations.
54namespace foundation { class DictionaryArray; }
55namespace foundation { class Image; }
56namespace foundation { class ImageAttributes; }
57namespace foundation { class LightingConditions; }
58namespace foundation { class Tile; }
59namespace renderer { class ImageStack; }
60namespace renderer { class ParamArray; }
61
62namespace renderer
63{
64
65//
66// Frame class.
67//
68// Pixels in a frame are always expressed in the linear RGB color space.
69//
70
71class APPLESEED_DLLSYMBOL Frame
72 : public Entity
73{
74 public:
75 // Return the unique ID of this class of entities.
76 static foundation::UniqueID get_class_uid();
77
78 // Delete this instance.
79 virtual void release() APPLESEED_OVERRIDE;
80
81 // Print frame settings to the renderer's global logger.
82 void print_settings();
83
84 // Return the name of the active camera.
85 const char* get_active_camera_name() const;
86
87 // Access the main underlying image.
88 foundation::Image& image() const;
89
90 // Access the AOV images.
91 ImageStack& aov_images() const;
92
93 // Return the reconstruction filter used by the main image and the AOV images.
94 const foundation::Filter2f& get_filter() const;
95
96 // Return the color space the frame should be converted to for display.
97 foundation::ColorSpace get_color_space() const;
98
99 // Return the lighting conditions for spectral-to-RGB conversions.
100 const foundation::LightingConditions& get_lighting_conditions() const;
101
102 // Return true if the frame uses premultiplied alpha, false if it uses straight alpha.
103 bool is_premultiplied_alpha() const;
104
105 // Set/get the crop window. The crop window is inclusive on all sides.
106 void reset_crop_window();
107 bool has_crop_window() const;
108 void set_crop_window(const foundation::AABB2u& crop_window);
109 const foundation::AABB2u& get_crop_window() const;
110
111 // Return the number of pixels in the frame, taking into account the crop window.
112 size_t get_pixel_count() const;
113
114 // Convert a tile or an image from linear RGB to the output color space.
115 void transform_to_output_color_space(foundation::Tile& tile) const;
116 void transform_to_output_color_space(foundation::Image& image) const;
117
118 // Return the normalized device coordinates of a given sample.
119 foundation::Vector2d get_sample_position(
120 const double sample_x, // x coordinate of the sample in the image, in [0,width)
121 const double sample_y) const; // y coordinate of the sample in the image, in [0,height)
122 foundation::Vector2d get_sample_position(
123 const size_t pixel_x, // x coordinate of the pixel in the image
124 const size_t pixel_y, // y coordinate of the pixel in the image
125 const double sample_x, // x coordinate of the sample in the pixel, in [0,1)
126 const double sample_y) const; // y coordinate of the sample in the pixel, in [0,1)
127 foundation::Vector2d get_sample_position(
128 const size_t tile_x, // x coordinate of the tile in the image
129 const size_t tile_y, // y coordinate of the tile in the image
130 const size_t pixel_x, // x coordinate of the pixel in the tile
131 const size_t pixel_y, // y coordinate of the pixel in the tile
132 const double sample_x, // x coordinate of the sample in the pixel, in [0,1)
133 const double sample_y) const; // y coordinate of the sample in the pixel, in [0,1)
134
135 // Clear the main image to transparent black.
136 void clear_main_image();
137
138 // Write the main image / the AOV images to disk.
139 // Return true if successful, false otherwise.
140 bool write_main_image(const char* file_path) const;
141 bool write_aov_images(const char* file_path) const;
142
143 // Archive the frame to a given directory on disk. If output_path is provided,
144 // the full path to the output file will be returned. The returned string must
145 // be freed using foundation::free_string().
146 // Return true if successful, false otherwise.
147 bool archive(
148 const char* directory,
149 char** output_path = 0) const;
150
151 private:
152 friend class FrameFactory;
153
154 struct Impl;
155 Impl* impl;
156
157 foundation::CanvasProperties m_props;
158 foundation::ColorSpace m_color_space;
159 bool m_is_premultiplied_alpha;
160
161 // Constructor.
162 Frame(
163 const char* name,
164 const ParamArray& params);
165
166 // Destructor.
167 ~Frame();
168
169 void extract_parameters();
170
171 // Write an image to disk after transformation to the frame's color space.
172 // Return true if successful, false otherwise.
173 bool write_image(
174 const char* file_path,
175 const foundation::Image& image,
176 const foundation::ImageAttributes& image_attributes) const;
177};
178
179
180//
181// FrameFactory class implementation.
182//
183
184class APPLESEED_DLLSYMBOL FrameFactory
185{
186 public:
187 // Return a set of input metadata for frames.
188 static foundation::DictionaryArray get_input_metadata();
189
190 // Create a new frame.
191 static foundation::auto_release_ptr<Frame> create(
192 const char* name,
193 const ParamArray& params);
194};
195
196
197//
198// Frame class implementation.
199//
200
201inline foundation::ColorSpace Frame::get_color_space() const
202{
203 return m_color_space;
204}
205
206inline bool Frame::is_premultiplied_alpha() const
207{
208 return m_is_premultiplied_alpha;
209}
210
211inline foundation::Vector2d Frame::get_sample_position(
212 const double sample_x,
213 const double sample_y) const
214{
215 return
216 foundation::Vector2d(
217 sample_x * m_props.m_rcp_canvas_width,
218 sample_y * m_props.m_rcp_canvas_height);
219}
220
221inline foundation::Vector2d Frame::get_sample_position(
222 const size_t pixel_x,
223 const size_t pixel_y,
224 const double sample_x,
225 const double sample_y) const
226{
227 return
228 get_sample_position(
229 pixel_x + sample_x,
230 pixel_y + sample_y);
231}
232
233inline foundation::Vector2d Frame::get_sample_position(
234 const size_t tile_x,
235 const size_t tile_y,
236 const size_t pixel_x,
237 const size_t pixel_y,
238 const double sample_x,
239 const double sample_y) const
240{
241 assert(tile_x < m_props.m_tile_count_x);
242 assert(tile_y < m_props.m_tile_count_y);
243
244 return
245 get_sample_position(
246 tile_x * m_props.m_tile_width + pixel_x,
247 tile_y * m_props.m_tile_height + pixel_y,
248 sample_x,
249 sample_y);
250}
251
252} // namespace renderer
253
254#endif // !APPLESEED_RENDERER_MODELING_FRAME_FRAME_H
255