1 #ifndef DALI_RENDERER_H
2 #define DALI_RENDERER_H
5 * Copyright (c) 2022 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
22 #include <dali/public-api/object/handle.h> // Dali::Handle
23 #include <dali/public-api/object/property-index-ranges.h> // DEFAULT_RENDERER_PROPERTY_START_INDEX
24 #include <dali/public-api/rendering/geometry.h> // Dali::Geometry
25 #include <dali/public-api/rendering/texture-set.h> // Dali::TextureSet
32 * @addtogroup dali_core_rendering_effects
36 namespace Internal DALI_INTERNAL
41 namespace FaceCullingMode
44 * @brief Enumeration for face culling mode.
49 NONE, ///< None of the faces should be culled @SINCE_1_1.43
50 FRONT, ///< Cull front face, front faces should never be shown @SINCE_1_1.43
51 BACK, ///< Cull back face, back faces should never be shown @SINCE_1_1.43
52 FRONT_AND_BACK, ///< Cull front and back faces; if the geometry is composed of triangles none of the faces will be shown @SINCE_1_1.43
55 } // namespace FaceCullingMode
60 * @brief Enumeration for blend mode.
65 OFF, ///< Blending is disabled. @SINCE_1_1.43
66 AUTO, ///< Blending is enabled if there is alpha channel. This is the default mode. @SINCE_1_1.43
67 ON, ///< Blending is enabled. @SINCE_1_1.43
68 ON_WITHOUT_CULL, ///< Blending is enabled, and don't cull the renderer @SINCE_2_0.43
69 USE_ACTOR_OPACITY ///< Blending is enabled when the actor is not opaque @SINCE_2_2.7
72 } // namespace BlendMode
74 namespace BlendEquation
77 * @brief Enumeration for blend equation.
82 ADD = 0x8006, ///< The source and destination colors are added to each other. @SINCE_1_1.43
83 SUBTRACT = 0x800A, ///< Subtracts the destination from the source. @SINCE_1_1.43
84 REVERSE_SUBTRACT = 0x800B ///< Subtracts the source from the destination. @SINCE_1_1.43
87 } // namespace BlendEquation
92 * @brief Enumeration for blend factor.
97 ZERO = 0, ///< ZERO @SINCE_1_1.43
98 ONE = 1, ///< ONE @SINCE_1_1.43
99 SRC_COLOR = 0x0300, ///< SRC_COLOR @SINCE_1_1.43
100 ONE_MINUS_SRC_COLOR = 0x0301, ///< ONE_MINUS_SRC_COLOR @SINCE_1_1.43
101 SRC_ALPHA = 0x0302, ///< SRC_ALPHA @SINCE_1_1.43
102 ONE_MINUS_SRC_ALPHA = 0x0303, ///< ONE_MINUS_SRC_ALPHA @SINCE_1_1.43
103 DST_ALPHA = 0x0304, ///< DST_ALPHA @SINCE_1_1.43
104 ONE_MINUS_DST_ALPHA = 0x0305, ///< ONE_MINUS_DST_ALPHA @SINCE_1_1.43
105 DST_COLOR = 0x0306, ///< DST_COLOR @SINCE_1_1.43
106 ONE_MINUS_DST_COLOR = 0x0307, ///< ONE_MINUS_DST_COLOR @SINCE_1_1.43
107 SRC_ALPHA_SATURATE = 0x0308, ///< SRC_ALPHA_SATURATE @SINCE_1_1.43
108 CONSTANT_COLOR = 0x8001, ///< CONSTANT_COLOR @SINCE_1_1.43
109 ONE_MINUS_CONSTANT_COLOR = 0x8002, ///< ONE_MINUS_CONSTANT_COLOR @SINCE_1_1.43
110 CONSTANT_ALPHA = 0x8003, ///< CONSTANT_ALPHA @SINCE_1_1.43
111 ONE_MINUS_CONSTANT_ALPHA = 0x8004 ///< ONE_MINUS_CONSTANT_ALPHA @SINCE_1_1.43
114 } // namespace BlendFactor
116 namespace DepthWriteMode
119 * @brief Enumeration for depth buffer write modes.
124 OFF, ///< Renderer doesn't write to the depth buffer @SINCE_1_1.43
125 AUTO, ///< Renderer only writes to the depth buffer if it's opaque @SINCE_1_1.43
126 ON ///< Renderer writes to the depth buffer @SINCE_1_1.43
129 } // namespace DepthWriteMode
131 namespace DepthTestMode
134 * @brief Enumeration for depth buffer test (read) modes.
139 OFF, ///< Renderer does not read from the depth buffer @SINCE_1_1.43
140 AUTO, ///< Renderer only reads from the depth buffer if in a 3D layer @SINCE_1_1.43
141 ON ///< Renderer reads from the depth buffer based on the DepthFunction @SINCE_1_1.43
144 } // namespace DepthTestMode
146 namespace DepthFunction
149 * @brief Enumeration for depth functions.
154 NEVER, ///< Depth test never passes @SINCE_1_1.43
155 ALWAYS, ///< Depth test always passes @SINCE_1_1.43
156 LESS, ///< Depth test passes if the incoming depth value is less than the stored depth value @SINCE_1_1.43
157 GREATER, ///< Depth test passes if the incoming depth value is greater than the stored depth value @SINCE_1_1.43
158 EQUAL, ///< Depth test passes if the incoming depth value is equal to the stored depth value @SINCE_1_1.43
159 NOT_EQUAL, ///< Depth test passes if the incoming depth value is not equal to the stored depth value @SINCE_1_1.43
160 LESS_EQUAL, ///< Depth test passes if the incoming depth value is less than or equal to the stored depth value @SINCE_1_1.43
161 GREATER_EQUAL ///< Depth test passes if the incoming depth value is greater than or equal to the stored depth value @SINCE_1_1.43
164 } // namespace DepthFunction
169 * @brief Enumeration for the controls of how this renderer uses its stencil properties and writes to the color buffer.
174 NONE, ///< Do not write to either color or stencil buffer (But will potentially render to depth buffer). @SINCE_1_2_5
175 AUTO, ///< Managed by the Actor Clipping API. This is the default. @SINCE_1_2_5
176 COLOR, ///< Ingore stencil properties. Write to the color buffer. @SINCE_1_2_5
177 STENCIL, ///< Use the stencil properties. Do not write to the color buffer. @SINCE_1_2_5
178 COLOR_STENCIL ///< Use the stencil properties AND Write to the color buffer. @SINCE_1_2_5
181 } // namespace RenderMode
183 namespace StencilFunction
186 * @brief Enumeration for the comparison function used on the stencil buffer.
191 NEVER, ///< Always fails @SINCE_1_1.43
192 LESS, ///< Passes if ( reference & mask ) < ( stencil & mask ) @SINCE_1_1.43
193 EQUAL, ///< Passes if ( reference & mask ) = ( stencil & mask ) @SINCE_1_1.43
194 LESS_EQUAL, ///< Passes if ( reference & mask ) <= ( stencil & mask ) @SINCE_1_1.43
195 GREATER, ///< Passes if ( reference & mask ) > ( stencil & mask ) @SINCE_1_1.43
196 NOT_EQUAL, ///< Passes if ( reference & mask ) != ( stencil & mask ) @SINCE_1_1.43
197 GREATER_EQUAL, ///< Passes if ( reference & mask ) >= ( stencil & mask ) @SINCE_1_1.43
198 ALWAYS, ///< Always passes @SINCE_1_1.43
201 } // namespace StencilFunction
203 namespace StencilOperation
206 * @brief Enumeration for specifying the action to take when the stencil (or depth) test fails during stencil test.
211 ZERO, ///< Sets the stencil buffer value to 0 @SINCE_1_1.43
212 KEEP, ///< Keeps the current value @SINCE_1_1.43
213 REPLACE, ///< Sets the stencil buffer value to ref, as specified by glStencilFunc @SINCE_1_1.43
214 INCREMENT, ///< Increments the current stencil buffer value. Clamps to the maximum representable unsigned value @SINCE_1_1.43
215 DECREMENT, ///< Decrements the current stencil buffer value. Clamps to 0 @SINCE_1_1.43
216 INVERT, ///< Bitwise inverts the current stencil buffer value @SINCE_1_1.43
217 INCREMENT_WRAP, ///< Increments the current stencil buffer value. Wraps stencil buffer value to zero when incrementing the maximum representable unsigned value @SINCE_1_1.43
218 DECREMENT_WRAP ///< Decrements the current stencil buffer value. Wraps stencil buffer value to the maximum representable unsigned value when decrementing a stencil buffer value of zero @SINCE_1_1.43
221 } // namespace StencilOperation
224 * @brief Renderer is a handle to an object used to show content by combining a Geometry, a TextureSet and a shader.
228 class DALI_CORE_API Renderer : public Handle
232 * @brief Enumeration for instances of properties belonging to the Renderer class.
238 * @brief Enumeration for instances of properties belonging to the Renderer class.
244 * @brief Name "depthIndex", type INTEGER.
246 * @note The default value is 0.
248 DEPTH_INDEX = DEFAULT_RENDERER_PROPERTY_START_INDEX,
251 * @brief Name "faceCullingMode", type INTEGER.
253 * @note The default value is FaceCullingMode::NONE.
258 * @brief Name "blendMode", type INTEGER.
260 * @note The default value is BlendMode::AUTO.
265 * @brief Name "blendEquationRgb", type INTEGER.
267 * @note The default value is BlendEquation::ADD.
272 * @brief Name "blendEquationAlpha", type INTEGER.
274 * @note The default value is BlendEquation::ADD.
276 BLEND_EQUATION_ALPHA,
279 * @brief Name "blendFactorSrcRgb", type INTEGER.
281 * @note The default value is BlendFactor::SRC_ALPHA.
283 BLEND_FACTOR_SRC_RGB,
286 * @brief Name "blendFactorDestRgb", type INTEGER.
288 * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA.
290 BLEND_FACTOR_DEST_RGB,
293 * @brief Name "blendFactorSrcAlpha", type INTEGER.
295 * @note The default value is BlendFactor::ONE.
297 BLEND_FACTOR_SRC_ALPHA,
300 * @brief Name "blendFactorDestAlpha", type INTEGER.
302 * @note The default value is BlendFactor::ONE_MINUS_SRC_ALPHA.
304 BLEND_FACTOR_DEST_ALPHA,
307 * @brief Name "blendColor", type VECTOR4.
309 * @note The default value is Color::TRANSPARENT.
314 * @brief Name "blendPreMultipledAlpha", type BOOLEAN.
316 * @note The default value is false.
318 BLEND_PRE_MULTIPLIED_ALPHA,
321 * @brief Name "indexRangeFirst", type INTEGER.
323 * @note The default value is 0.
328 * @brief Name "indexRangeCount", type INTEGER.
330 * @note The default (0) means that whole range of indices will be used.
335 * @brief Name "depthWriteMode", type INTEGER.
337 * @see DepthWriteMode
338 * @note The default value is DepthWriteMode::AUTO.
343 * @brief Name "depthFunction", type INTEGER.
346 * @note The default value is DepthFunction::LESS.
351 * @brief Name "depthTestMode", type INTEGER.
354 * @note The default value is DepthTestMode::AUTO.
359 * @brief Name "renderMode", type INTEGER.
362 * @note The default value is RenderMode::AUTO.
367 * @brief Name "stencilFunction", type INTEGER.
369 * @see StencilFunction
370 * @note The default value is StencilFunction::ALWAYS.
375 * @brief Name "stencilFunctionMask", type INTEGER.
377 * @note The default value is 0xFF.
379 STENCIL_FUNCTION_MASK,
382 * @brief Name "stencilFunctionReference", type INTEGER.
384 * @note The default value is 0.
386 STENCIL_FUNCTION_REFERENCE,
389 * @brief Name "stencilMask", type INTEGER.
391 * @note The default value is 0xFF.
396 * @brief Name "stencilOperationOnFail", type INTEGER.
398 * @see StencilOperation
399 * @note The default value is StencilOperation::KEEP
401 STENCIL_OPERATION_ON_FAIL,
404 * @brief Name "stencilOperationOnZFail", type INTEGER.
406 * @see StencilOperation
407 * @note The default value is StencilOperation::KEEP.
409 STENCIL_OPERATION_ON_Z_FAIL,
412 * @brief Name "stencilOperationOnZPass", type INTEGER.
414 * @see StencilOperation
415 * @note The default value is StencilOperation::KEEP.
417 STENCIL_OPERATION_ON_Z_PASS,
422 * @brief Creates a new Renderer object.
425 * @param[in] geometry Geometry to be used by this renderer
426 * @param[in] shader Shader to be used by this renderer
427 * @return A handle to the Renderer
429 static Renderer New(Geometry& geometry, Shader& shader);
432 * @brief Creates a new Renderer object with RenderCallback.
435 * @param[in] renderCallback Valid RenderCallback
436 * @return A handle to the Renderer
438 static Renderer New(RenderCallback& renderCallback);
441 * @brief Default constructor, creates an empty handle
455 * @brief Copy constructor, creates a new handle to the same object.
458 * @param[in] handle Handle to an object
460 Renderer(const Renderer& handle);
463 * @brief Downcasts to a renderer handle.
464 * If not, a renderer the returned renderer handle is left uninitialized.
467 * @param[in] handle Handle to an object
468 * @return Renderer handle or an uninitialized handle
470 static Renderer DownCast(BaseHandle handle);
473 * @brief Assignment operator, changes this handle to point at the same object.
476 * @param[in] handle Handle to an object
477 * @return Reference to the assigned object
479 Renderer& operator=(const Renderer& handle);
482 * @brief Move constructor.
485 * @param[in] rhs A reference to the moved handle
487 Renderer(Renderer&& rhs) noexcept;
490 * @brief Move assignment operator.
493 * @param[in] rhs A reference to the moved handle
494 * @return A reference to this handle
496 Renderer& operator=(Renderer&& rhs) noexcept;
499 * @brief Sets the geometry to be used by this renderer.
502 * @param[in] geometry The geometry to be used by this renderer
504 void SetGeometry(Geometry& geometry);
507 * @brief Gets the geometry used by this renderer.
510 * @return The geometry used by the renderer
512 Geometry GetGeometry() const;
515 * @brief Sets effective range of indices to draw from bound index buffer.
518 * @param[in] firstElement The First element to draw
519 * @param[in] elementsCount The number of elements to draw
521 inline void SetIndexRange(int firstElement, int elementsCount)
523 SetProperty(Property::INDEX_RANGE_FIRST, firstElement);
524 SetProperty(Property::INDEX_RANGE_COUNT, elementsCount);
528 * @brief Sets the texture set to be used by this renderer.
531 * @param[in] textureSet The texture set to be used by this renderer
533 void SetTextures(TextureSet& textureSet);
536 * @brief Gets the texture set used by this renderer.
539 * @return The texture set used by the renderer
541 TextureSet GetTextures() const;
544 * @brief Sets the shader used by this renderer.
547 * @param[in] shader The shader to be used by this renderer
549 void SetShader(Shader& shader);
552 * @brief Gets the shader used by this renderer.
555 * @return The shader used by the renderer
557 Shader GetShader() const;
560 * @brief Sets RenderCallback to be used for native rendering
563 * @param[in] callback Pointer to a valid RenderCallback object
565 void SetRenderCallback(RenderCallback* callback);
570 * @brief The constructor.
571 * @note Not intended for application developers.
573 * @param[in] pointer A pointer to a newly allocated Renderer
575 explicit DALI_INTERNAL Renderer(Internal::Renderer* pointer);
584 #endif // DALI_RENDERER_H