optional/dali-toolkit/public-api/shader-effects/displacement-effect.h

   1 #ifndef __DALI_TOOLKIT_SHADER_EFFECT_DISPLACEMENT_H__
   2 #define __DALI_TOOLKIT_SHADER_EFFECT_DISPLACEMENT_H__
   3
   4 /*
   5  * Copyright (c) 2014 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 // INTERNAL INCLUDES
  22 #include <dali/dali.h>
  23
  24 namespace Dali DALI_IMPORT_API
  25 {
  26
  27 namespace Toolkit
  28 {
  29
  30 /**
  31  *
  32  * Class for two state displacement effect shader that works on a per object basis. By passing a height-normal map as an effect image, the user can create
  33  * various styles of buttons on an image actor. The shader requires two height-normal maps in one image, one for each state.
  34  *
  35  *    The normals and height information for the two states of the button should be strictly specified in this format:
  36  *     ______________
  37  *    |   State 0    |
  38  *    |              |
  39  *    |              | --> Unpressed button normals in rgb and height in a
  40  *    |     Map      |
  41  *    |______________|
  42  *    |   State 1    |
  43  *    |              |
  44  *    |              | --> Pressed button normals in rgb and height in a
  45  *    |     Map      |
  46  *    |______________|
  47  *
  48  *    The RGB values should contain the surface normals and the alpha should contian the height map. For a better effect keep the highest point (alpha value) in
  49  *    the combined map as 1.0 and the lowest posint as 0.0 and 0.5 for any region which doesn't need displacement.
  50  *
  51  *    For the supplied Normal map the Y-Axis should be down, Meaning (0,0) is in the top left. As the shader inverts the Y axis for lighting calculation.
  52  *
  53  *    Limitations: Can be applied to ImageActor only, And doesn't provide support for specular color.
  54  *
  55  * Usage example:-
  56  *
  57  * // Create shader used for doing soft button\n
  58  * DisplacementEffect buttonEffect = DisplacementEffect::New();
  59  * buttonEffect.SetEffectImage(Image::New( FANCY_BUTTON_HEIGHT_MAP_IMAGE_PATH ););
  60  *
  61  * // set shader to the soft button\n
  62  * ImageActor fancyButton = ImageActor::New( ... );\n
  63  * fancyButton.SetShaderEffect( buttonEffect );
  64  *
  65  * // animate a button push, using e.g. AlphaFunctions::Bounce. With these values the button pushes in and out (animates to and fro between the two states)
  66  *
  67  *
  68  * Animation animation = Animation::New( ... );\n
  69  * animation.AnimateTo( Property(buttonEffect, buttonEffect.GetStatePropertyName()), 1.0f, AlphaFunctions::Bounce, ... );\n
  70  * animation.Play();\n
  71  *
  72  */
  73 class DisplacementEffect : public ShaderEffect
  74 {
  75
  76 public:
  77
  78   typedef enum
  79   {
  80     DISPLACED = 0,    /// Image gets displaced
  81     FIXED             /// Image does not displace. Useful for matching lighting between areas that do not displace and those that do, e.g for backgrounds which are visible between buttons.
  82   }Type;
  83
  84   /**
  85    * Create an uninitialized DisplacementEffect; this can be initialized with DisplacementEffect::New()
  86    * Calling member functions with an uninitialized Dali::Object is not allowed.
  87    */
  88   DisplacementEffect();
  89
  90   /**
  91    * Virtual destructor.
  92    */
  93   virtual ~DisplacementEffect();
  94
  95   /**
  96    * Create an initialized DisplacementEffect
  97    * @param type The type of the effect, can be either DISPLACED, or FIXED.
  98    * @return A handle to a newly allocated Dali resource.
  99    */
 100   static DisplacementEffect New(Type type);
 101
 102   /**
 103    * Get the name for the light direction property (Vector3)
 104    * The light direction is used in the lighting calculation. The angle of incidence directly affects the amount of light reflected.
 105    * Default (0.0f, 0.7070168f, 0.7071068f), i.e angled at the surface from in front and above.
 106    * @return A std::string containing the property name
 107    */
 108   const std::string& GetLightDirectionPropertyName() const;
 109
 110   /**
 111    * Get the name for the ambient lighting color property (Vector3)
 112    * The ambient light is used in the lighting calculation. Care must be taken to not saturate the image by setting this value too high,
 113    * or the indentation will not look correct. Default 0.15.
 114    * @return A std::string containing the property name
 115    */
 116   const std::string& GetAmbientLightColorPropertyName() const;
 117
 118   /**
 119    * Get the name for the diffuse light color property (Vector3).
 120    * The diffuse light is used in the lighting calculation. Default is (1.0f, 1.0f, 1.0f).
 121    * @return A std::string containing the property name
 122    */
 123   const std::string& GetDiffuseLightColorPropertyName() const;
 124
 125   /**
 126    * Get the name for the lighting multiplier property (float).
 127    * The ambient and diffuse lighting is multiplied by this factor. Since a diffuse light at an angle will cause the whole image to darken,
 128    * this property can be used to scale the image back up closer to the pixel values of the original diffuse texture. Care must be taken to not saturate the image,
 129    * or the indentation will not look correct. Default 1.0
 130    * @return A std::string containing the property name
 131    */
 132   const std::string& GetLightingMultiplierPropertyName() const;
 133
 134   /**
 135    * Get the name for the state property (float).
 136    * The shader can have a maximum of two end states 0 or 1, Animate between these two values to do the transitions between states.
 137    * Default 0.0
 138    * @return A std::string containing the property name.
 139    */
 140   const std::string& GetStatePropertyName() const;
 141
 142   /**
 143    * Get the name for the height scale property (float).
 144    * The height displacement is multiplied by this factor. Tweak this to get the required level of depth.
 145    * Default 0.1
 146    * @return A std::string containing the property name.
 147    */
 148   const std::string& GetHeightScalePropertyName() const;
 149
 150   /**
 151    * Get the name for the fixed normal property (Vector3).
 152    * Only applicable for the FIXED type shader and not for DISPLACEMENT type.
 153    * The Fixed normal will be used for the light calculation. Tweak this to get the required level of light.
 154    * Default (0.0f, 0.0f, 1.0f)
 155    * @return A std::string containing the property name.
 156    */
 157   const std::string& GetFixedNormalPropertyName() const;
 158
 159   /**
 160    * Set the light direction property
 161    * The light direction is used in the lighting calculation. The angle of incidence directly affects the amount of light reflected.
 162    * Default (0.0f, 0.7070168f, 0.7071068f), i.e angled at the surface from in front and above.
 163    * @param [in] lightDirection The new light direction.
 164    */
 165   void SetLightDirection(Vector3 lightDirection);
 166
 167   /**
 168    * Set the ambient light color property
 169    * The ambient light is used in the lighting calculation. Care must be taken to not saturate the image by setting this value too high,
 170    * or the indentation will not look correct. Default (0.15f, 0.15f, 0.15f).
 171    * @param [in] ambientLight The new ambient light value.
 172    */
 173   void SetAmbientLightColorProperty(Vector3 ambientLight);
 174
 175   /**
 176    * Set the diffuse light color property.
 177    * The diffuse light is used in the lighting calculation. Default is (1.0f, 1.0f, 1.0f), i.e. a white light so the natural image color is shown.
 178    * @param [in] diffuseLight The new diffuse light value.
 179    */
 180   void SetDiffuseLightColorProperty(Vector3 diffuseLight);
 181
 182   /**
 183    * Get the name for the lighting multiplier property.
 184    * The ambient and diffuse lighting is multiplied by this factor. Since a diffuse light at an angle will cause the whole image to darken,
 185    * this property can be used to scale the image back up closer to the pixel values of the original diffuse texture. Care must be taken to not saturate the image,
 186    * or the indentation will not look correct. Default 1.0
 187    * @param [in] lightMultiplier The new light multiplier value.
 188    */
 189   void SetLightingMultiplierProperty(float lightMultiplier);
 190
 191   /**
 192    * Get the name for the state property.
 193    * The shader can only be in or in between two states 0 or 1, Animate between these two values to do the transitions between states.
 194    * @param [in] state The new state value.
 195    */
 196   void SetStateProperty(float state);
 197
 198   /**
 199    * Set the name for the height scale property.
 200    * The height displacement is multiplied by this factor. Tweak this to get the required level of depth. Default 0.1
 201    * @param [in] heightScale The new height scale.
 202    */
 203   void SetHeightScaleProperty(float heightScale);
 204
 205   /**
 206    * Set the name for fixed normal property, Only applicable for the FIXED type shader and not for DISPLACEMENT type.
 207    * The Fixed normal will be used for the light calculation. Tweak this to get the required level of light.
 208    * @param [in] fixedNormal The new normal for the fixed type shader effect.
 209    */
 210   void SetFixedNormalProperty(Vector3 fixedNormal);
 211
 212 private:
 213   // Not intended for application developers
 214   DisplacementEffect(ShaderEffect handle);
 215 };
 216
 217 }
 218
 219 }
 220
 221 #endif //#ifndef __DALI_TOOLKIT_SHADER_EFFECT_DISPLACEMENT_H__
 222