dali/public-api/rendering/shader.h

   1 #ifndef DALI_SHADER_H
   2 #define DALI_SHADER_H
   3
   4 /*
   5  * Copyright (c) 2024 Samsung Electronics Co., Ltd.
   6  *
   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
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  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.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <string> // std::string
  23
  24 // INTERNAL INCLUDES
  25 #include <dali/public-api/object/handle.h>                // Dali::Handle
  26 #include <dali/public-api/object/property-index-ranges.h> // DEFAULT_DERIVED_HANDLE_PROPERTY_START_INDEX
  27 #include <dali/public-api/object/property-value.h>
  28
  29 /**
  30  * @brief DALI_COMPOSE_SHADER macro provides a convenient way to write shader source code.
  31  *
  32  * We normally use double quotation marks to write a string such as "Hello World".
  33  * However many symbols are needed to add multiple lines of string.
  34  * We don't need to write quotation marks using this macro at every line.
  35  *
  36  * [An example of double quotation marks usage]
  37  * <pre>
  38  * const string FRAGMENT_SHADER_SOURCE = \
  39  * "  void main()\n"
  40  * "  {\n"
  41  * "    gl_FragColor = texture2D( sTexture, vTexCoord ) * uColor;\n"
  42  * "  }\n";
  43  * </pre><br/>
  44  * [An example of DALI_COMPOSE_SHADER usage]
  45  * <pre>
  46  * const string VERTEX_SHADER_SOURCE = DALI_COMPOSE_SHADER (
  47  *   void main()
  48  *   {
  49  *     gl_Position = uProjection * uModelView * vec4(aPosition, 1.0);
  50  *     vTexCoord = aTexCoord;
  51  *   }
  52  * );
  53  * </pre>
  54  *
  55  * @SINCE_1_1.43
  56  */
  57 #define DALI_COMPOSE_SHADER(STR) #STR
  58
  59 namespace Dali
  60 {
  61 /**
  62  * @addtogroup dali_core_rendering_effects
  63  * @{
  64  */
  65
  66 namespace Internal DALI_INTERNAL
  67 {
  68 class Shader;
  69 }
  70
  71 /**
  72  * @brief Shaders allows custom vertex and color transformations in the GPU.
  73  *
  74  * @SINCE_1_1.43
  75  */
  76 class DALI_CORE_API Shader : public Handle
  77 {
  78 public:
  79   /**
  80    * @brief Hints for rendering.
  81    * @SINCE_1_1.45
  82    */
  83   struct Hint
  84   {
  85     /**
  86      * @brief Enumeration for the hint value.
  87      * @SINCE_1_1.45
  88      */
  89     enum Value
  90     {
  91       NONE                  = 0x00, ///< No hints                                                                          @SINCE_1_1.45
  92       OUTPUT_IS_TRANSPARENT = 0x01, ///< Might generate transparent alpha from opaque inputs                               @SINCE_1_1.45
  93       MODIFIES_GEOMETRY     = 0x02, ///< Might change position of vertices, this option disables any culling optimizations @SINCE_1_1.45
  94     };
  95   };
  96
  97   /**
  98    * @brief Enumeration for instances of properties belonging to the Shader class.
  99    * @SINCE_1_1.43
 100    */
 101   struct Property
 102   {
 103     /**
 104      * @brief Enumeration for instances of properties belonging to the Shader class.
 105      * @SINCE_1_1.43
 106      */
 107     enum
 108     {
 109       /**
 110        * @brief Name: "program", Type: MAP or ARRAY.
 111        * @note The default value is empty.
 112        * @note It is Property::Map or Property::Array of the map.
 113        * @note Format: {"renderPassTag":"", "vertex":"", "fragment":"", "hints":"", "name":""}
 114        * @SINCE_1_1.43
 115        */
 116       PROGRAM = DEFAULT_OBJECT_PROPERTY_START_INDEX,
 117     };
 118   };
 119
 120   /**
 121    * @brief Creates Shader.
 122    *
 123    * @SINCE_1_1.43
 124    * @param[in] vertexShader Vertex shader code for the effect.
 125    * @param[in] fragmentShader Fragment Shader code for the effect.
 126    * @param[in] hints Hints to define the geometry of the rendered object
 127    * @param[in] shaderName The name of this shader. (optional)
 128    * @return A handle to a shader effect
 129    */
 130   static Shader New(std::string_view vertexShader,
 131                     std::string_view fragmentShader,
 132                     Hint::Value      hints      = Hint::NONE,
 133                     std::string_view shaderName = "");
 134
 135   /**
 136    * @brief Creates Shader.
 137    *
 138    * @SINCE_2_2.31
 139    * @param[in] shaderMap Property::Map of shader data or Property::Array of Property::Map.
 140    * Property::Map format is {"renderPassTag":"", "vertex":"", "fragment":"", "hints":""}
 141    * shaderMap can be Property::Array of Property::Map for multi pass shading.
 142    * @return A handle to a shader effect
 143    */
 144   static Shader New(Dali::Property::Value shaderMap);
 145
 146   /**
 147    * @brief Default constructor, creates an empty handle.
 148    *
 149    * @SINCE_1_1.43
 150    */
 151   Shader();
 152
 153   /**
 154    * @brief Destructor.
 155    * This is non-virtual since derived Handle types must not contain data or virtual methods.
 156    *
 157    * @SINCE_1_1.43
 158    */
 159   ~Shader();
 160
 161   /**
 162    * @brief Copy constructor.
 163    *
 164    * @SINCE_1_1.43
 165    * @param[in] handle A handle to a Shader object
 166    */
 167   Shader(const Shader& handle);
 168
 169   /**
 170    * @brief Downcasts to a shader handle.
 171    * If not, a shader the returned shader handle is left uninitialized.
 172    *
 173    * @SINCE_1_1.43
 174    * @param[in] handle Handle to an object
 175    * @return Shader handle or an uninitialized handle
 176    */
 177   static Shader DownCast(BaseHandle handle);
 178
 179   /**
 180    * @brief Assignment operator, changes this handle to point at the same object.
 181    *
 182    * @SINCE_1_1.43
 183    * @param[in] handle Handle to an object
 184    * @return Reference to the assigned object
 185    */
 186   Shader& operator=(const Shader& handle);
 187
 188   /**
 189    * @brief Move constructor.
 190    *
 191    * @SINCE_1_9.22
 192    * @param[in] rhs A reference to the moved handle
 193    */
 194   Shader(Shader&& rhs) noexcept;
 195
 196   /**
 197    * @brief Move assignment operator.
 198    *
 199    * @SINCE_1_9.22
 200    * @param[in] rhs A reference to the moved handle
 201    * @return A reference to this
 202    */
 203   Shader& operator=(Shader&& rhs) noexcept;
 204
 205   /**
 206    * @brief Get shader preprocessor of shading language version.
 207    * @note This can potentially block until GL has been initialized
 208    * when the first time any DALi application is launched in the system.
 209    * @SINCE_1_9.36
 210    * @return shader preprocessor string.
 211    */
 212   static std::string GetShaderVersionPrefix();
 213
 214   /**
 215    * @brief Get vertex shader preprocessor that includes shading language version.
 216    * @note This can potentially block until GL has been initialized
 217    * when the first time any DALi application is launched in the system.
 218    * @SINCE_1_9.36
 219    * @return Vertex shader preprocessor string.
 220    */
 221   static std::string GetVertexShaderPrefix();
 222
 223   /**
 224    * @brief Get fragment shader preprocessor that includes shading language version.
 225    * @note This can potentially block until GL has been initialized
 226    * when the first time any DALi application is launched in the system.
 227    * @SINCE_1_9.36
 228    * @return Fragment shader preprocessor string.
 229    */
 230   static std::string GetFragmentShaderPrefix();
 231
 232 public:
 233   /**
 234    * @brief This constructor is used by Dali New() methods.
 235    * @note  Not intended for application developers.
 236    * @SINCE_1_1.43
 237    * @param[in] effect A pointer to a newly allocated Dali resource.
 238    */
 239   explicit DALI_INTERNAL Shader(Internal::Shader* effect);
 240 };
 241
 242 /**
 243  * @}
 244  */
 245 } // namespace Dali
 246
 247 #endif // DALI_SHADER_H