1//************************************ bs::framework - Copyright 2018 Marko Pintera **************************************//
2//*********** Licensed under the MIT license. See LICENSE.md for full terms. This notice is not to be removed. ***********//
3#pragma once
4
5#include "BsCorePrerequisites.h"
6#include "Image/BsPixelUtil.h"
7#include "RenderAPI/BsViewport.h"
8#include "CoreThread/BsCoreObject.h"
9#include "Utility/BsEvent.h"
10
11namespace bs
12{
13 /** @addtogroup RenderAPI
14 * @{
15 */
16
17 /** Structure that contains information about what part of the texture represents the render surface. */
18 struct BS_CORE_EXPORT RENDER_SURFACE_DESC
19 {
20 RENDER_SURFACE_DESC() { }
21
22 HTexture texture;
23
24 /** First face of the texture to bind (array index in texture arrays, or Z slice in 3D textures). */
25 UINT32 face = 0;
26
27 /**
28 * Number of faces to bind (entries in a texture array, or Z slices in 3D textures). When zero the entire resource
29 * will be bound.
30 */
31 UINT32 numFaces = 0;
32
33 /** If the texture has multiple mips, which one to bind (only one can be bound for rendering). */
34 UINT32 mipLevel = 0;
35 };
36
37 namespace ct
38 {
39 /**
40 * @see bs::RENDER_SURFACE_DESC
41 *
42 * @note References core textures instead of texture handles.
43 */
44 struct BS_CORE_EXPORT RENDER_SURFACE_DESC
45 {
46 RENDER_SURFACE_DESC() { }
47
48 SPtr<Texture> texture;
49
50 /** First face of the texture to bind (array index in texture arrays, or Z slice in 3D textures). */
51 UINT32 face = 0;
52
53 /**
54 * Number of faces to bind (entries in a texture array, or Z slices in 3D textures). When zero the entire resource
55 * will be bound.
56 */
57 UINT32 numFaces = 0;
58
59 /** If the texture has multiple mips, which one to bind (only one can be bound for rendering). */
60 UINT32 mipLevel = 0;
61 };
62 }
63
64 /** Contains various properties that describe a render target. */
65 class BS_CORE_EXPORT RenderTargetProperties
66 {
67 public:
68 virtual ~RenderTargetProperties() = default;
69
70 /** Width of the render target, in pixels. */
71 UINT32 width = 0;
72
73 /** Height of the render target, in pixels. */
74 UINT32 height = 0;
75
76 /**
77 * Number of three dimensional slices of the render target. This will be number of layers for array
78 * textures or number of faces cube textures.
79 */
80 UINT32 numSlices = 0;
81
82 /**
83 * Controls in what order is the render target rendered to compared to other render targets. Targets with higher
84 * priority will be rendered before ones with lower priority.
85 */
86 INT32 priority = 0;
87
88 /**
89 * True if the render target will wait for vertical sync before swapping buffers. This will eliminate
90 * tearing but may increase input latency.
91 */
92 bool vsync = false;
93
94 /**
95 * Controls how often should the frame be presented in respect to display device refresh rate. Normal value is 1
96 * where it will match the refresh rate. Higher values will decrease the frame rate (for example present interval of
97 * 2 on 60Hz refresh rate will display at most 30 frames per second).
98 */
99 UINT32 vsyncInterval = 1;
100
101 /** True if pixels written to the render target will be gamma corrected. */
102 bool hwGamma = false;
103
104 /**
105 * Does the texture need to be vertically flipped because of different screen space coordinate systems. (Determines
106 * is origin top left or bottom left. Engine default is top left.)
107 */
108 bool requiresTextureFlipping = false;
109
110 /** True if the target is a window, false if an offscreen target. */
111 bool isWindow = false;
112
113 /** Controls how many samples are used for multisampling. (0 or 1 if multisampling is not used). */
114 UINT32 multisampleCount = 0;
115 };
116
117 /**
118 * Render target is a frame buffer or a texture that the render system renders the scene to.
119 *
120 * @note
121 * Sim thread unless noted otherwise. Retrieve core implementation from getCore() for core thread only functionality.
122 */
123 class BS_CORE_EXPORT BS_SCRIPT_EXPORT(m:Rendering) RenderTarget : public IReflectable, public CoreObject
124 {
125 public:
126 RenderTarget();
127 virtual ~RenderTarget() = default;
128
129 /** Queries the render target for a custom attribute. This may be anything and is implementation specific. */
130 virtual void getCustomAttribute(const String& name, void* pData) const;
131
132 /**
133 * @copydoc ct::RenderTarget::setPriority
134 *
135 * @note This is an @ref asyncMethod "asynchronous method".
136 */
137 void setPriority(INT32 priority);
138
139 /**
140 * Returns properties that describe the render target.
141 *
142 * @note Sim thread only.
143 */
144 const RenderTargetProperties& getProperties() const;
145
146 /** Retrieves a core implementation of a render target usable only from the core thread. */
147 SPtr<ct::RenderTarget> getCore() const;
148
149 /**
150 * Event that gets triggered whenever the render target is resized.
151 *
152 * @note Sim thread only.
153 */
154 mutable Event<void()> onResized;
155
156 protected:
157 friend class ct::RenderTarget;
158
159 /** Returns properties that describe the render target. */
160 virtual const RenderTargetProperties& getPropertiesInternal() const = 0;
161
162 /************************************************************************/
163 /* SERIALIZATION */
164 /************************************************************************/
165 public:
166 friend class RenderTargetRTTI;
167 static RTTITypeBase* getRTTIStatic();
168 RTTITypeBase* getRTTI() const override;
169 };
170
171 /** @} */
172
173 namespace ct
174 {
175 /** @addtogroup RenderAPI-Internal
176 * @{
177 */
178
179 /**
180 * Provides access to internal render target implementation usable only from the core thread.
181 *
182 * @note Core thread only.
183 */
184 class BS_CORE_EXPORT RenderTarget : public CoreObject
185 {
186 public:
187 /** Frame buffer type when double-buffering is used. */
188 enum FrameBuffer
189 {
190 FB_FRONT,
191 FB_BACK,
192 FB_AUTO
193 };
194
195 RenderTarget();
196 virtual ~RenderTarget() = default;
197
198 /**
199 * Sets a priority that determines in which orders the render targets the processed.
200 *
201 * @param[in] priority The priority. Higher value means the target will be rendered sooner.
202 */
203 void setPriority(INT32 priority);
204
205 /**
206 * Swaps the frame buffers to display the next frame.
207 *
208 * @param[in] syncMask Optional synchronization mask that determines for which queues should the system wait
209 * before performing the swap buffer operation. By default the system waits for all queues.
210 * However if certain queues are performing non-rendering operations, or operations not
211 * related to this render target, you can exclude them from the sync mask for potentially
212 * better performance. You can use CommandSyncMask to generate a valid sync mask.
213 */
214 virtual void swapBuffers(UINT32 syncMask = 0xFFFFFFFF) {}
215
216 /** Queries the render target for a custom attribute. This may be anything and is implementation specific. */
217 virtual void getCustomAttribute(const String& name, void* pData) const;
218
219 /** Returns properties that describe the render target. */
220 const RenderTargetProperties& getProperties() const;
221
222 protected:
223 friend class bs::RenderTarget;
224
225 /** Returns properties that describe the render target. */
226 virtual const RenderTargetProperties& getPropertiesInternal() const = 0;
227 };
228
229 /** @} */
230 }
231}
232