dali/public-api/rendering/shader.h

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