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

   1 #ifndef __DALI_TOOLKIT_SHADER_EFFECT_SOFT_BUTTON_H__
   2 #define __DALI_TOOLKIT_SHADER_EFFECT_SOFT_BUTTON_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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 // INTERNAL INCLUDES
  21 #include <dali/dali.h>
  22
  23 namespace Dali DALI_IMPORT_API
  24 {
  25
  26 namespace Toolkit
  27 {
  28
  29 /**
  30  *
  31  * Class for soft button shader that works on a per object basis. Using animatable parameters user can create effect of button pushing in / out. Can be applied to ImageActor only.
  32  *
  33  * Usage example:-
  34  *
  35  * // Create shader used for doing soft button\n
  36  * SoftButtonEffect softButtonEffect = SoftButtonEffect::New();
  37  *
  38  * // set image actor shader to the soft button one\n
  39  * ImageActor imageActor = ImageActor::New( ... );\n
  40  * imageActor.SetShaderEffect( softButtonEffect );
  41  *
  42  * // animate a button push, using e.g. AlphaFunctions::Bounce. With these values the button pushes in and pops out slightly at the end\n
  43  * Animation animation = Animation::New( ... );\n
  44  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetLightingIndentationAmountPropertyName()), 0.25f, AlphaFunctions::Bounce, ... );\n
  45  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetLightingIndentationAmountPropertyName()), -0.05f, AlphaFunctions::Bounce, ... );\n
  46  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetTextureDistortionAmountPropertyName()), 0.25f, AlphaFunctions::Bounce, ... );\n
  47  * animation.AnimateTo( Property(softButtonEffect, softButtonEffect.GetTextureDistortionAmountPropertyName()), -0.05f, AlphaFunctions::Bounce, ... );\n
  48  * animation.Play();\n
  49  *
  50  */
  51 class SoftButtonEffect : public ShaderEffect
  52 {
  53
  54 public:
  55
  56   /**
  57    * Create an uninitialized SoftButtonEffect; this can be initialized with SoftButtonEffect::New()
  58    * Calling member functions with an uninitialized Dali::Object is not allowed.
  59    */
  60   SoftButtonEffect();
  61
  62   /**
  63    * Virtual destructor.
  64    */
  65   virtual ~SoftButtonEffect();
  66
  67   typedef enum
  68   {
  69     ELLIPTICAL = 0,   /// Button is elliptical
  70     RECTANGULAR,      /// Button is rectangular
  71     FIXED             /// Button does not indent (move). Useful for matching lighting between areas that do not indent (which can thus use a cheaper shader) and those that do indent.
  72   }Type;
  73
  74   /**
  75    * Create an initialized SoftButtonEffect
  76    * @param type The type of the soft button, can be either ELLIPTICAL, RECTANGULAR, or FIXED.
  77    * @return A handle to a newly allocated Dali resource.
  78    */
  79   static SoftButtonEffect New(Type type);
  80
  81   /**
  82    * Get the name for the lighting indentation amount property (float). Useful for animation.
  83    * This property changes the lighting, to make it look like the button is pushed in. User should animate this in conjunction
  84    * with texture distortion. Allowable values range from [-1..1], higher values give more change in lighting. Default 0.0 (no lighting change).
  85    * See also GetTextureDistortionAmountPropertyName().
  86    * @return A std::string containing the property name
  87    */
  88   const std::string& GetLightingIndentationAmountPropertyName() const;
  89
  90   /**
  91    * Get the name for the texture distortion amount property (float). Useful for animation.
  92    * This property changes the distortion, to make it look like the button is pushed in. User should animate this is conjunction
  93    * with lighting indentation. Allowable values range from [-1..1) - note 1.0 is NOT allowed - higher values give more distortion. Default 0.0 (no distortion).
  94    * See also GetLightingIndentationAmountPropertyName().
  95    * @return A std::string containing the property name
  96    */
  97   const std::string& GetTextureDistortionAmountPropertyName() const;
  98
  99   /**
 100    * Get the name for the ambient lighting amount property (float)
 101    * The ambient light is used in the lighting calculation. Care must be taken to not saturate the image by setting this value too high,
 102    * or the indentation will not look correct. Default 0.15.
 103    * @return A std::string containing the property name
 104    */
 105   const std::string& GetAmbientLightAmountPropertyName() const;
 106
 107   /**
 108    * Get the name for the diffuse light property (Vector3).
 109    * The diffuse light is used in the lighting calculation. Default is (0.0, 0.7070168, 0.7070168), i.e. a light angled at the surface from in front and above. Note that
 110    * you need to Normalize() the Vector3 that you set with this property.
 111    * @return A std::string containing the property name
 112    */
 113   const std::string& GetDiffuseLightPropertyName() const;
 114
 115   /**
 116    * Get the name for the lighting multiplier property (float).
 117    * The ambient and diffuse lighting is multiplied by this factor. Since a diffuse light at an angle will cause the whole image to darken, even outside the soft button
 118    * indentation, 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,
 119    * or the indentation will not look correct. Default 1.2.
 120    * @return A std::string containing the property name
 121    */
 122   const std::string& GetLightingMultiplierPropertyName() const;
 123
 124   /**
 125    * Get the name for the inside shape size scale property (float).
 126    * The SoftButtonEffect consists of two shapes, one inside the other. The outside shape fits exactly to the actor, touching its edges but completely contained. The inside
 127    * shape size is given by a multiplier of the outside shape size. For example a value of 0.5 means that the inside shape is half the size of the outside one. Allowable
 128    * values are in the range (0.0 - 1.0), note that 0.0 and 1.0 themselves are not allowed. Default 0.75.
 129    * See also GetOutsideShapeDepthPropertyName().
 130    * @return A std::string containing the property name
 131    */
 132   const std::string& GetInsideShapeSizeScalePropertyName() const;
 133
 134   /**
 135    * Get the name for the outside shape depth property (float).
 136    * The SoftButtonEffect consists of two shapes, one inside the other. The depth of the indentation at the transition between the inside and outside shapes is controlled by
 137    * this property. The values lies in the range [0.0 - 1.0]. A value of 0.0 means the outside shape has no depth (and is thus invisible), value of 1.0 means the outside shape
 138    * has maximum depth (and the inside shape is thus invisible). Default 0.05.
 139    * See also GetInsideShapeSizeScalePropertyName().
 140    * @return A std::string containing the property name
 141    */
 142   const std::string& GetOutsideShapeDepthPropertyName() const;
 143
 144   /**
 145    * Get the name for the effect pixel area property (Vector4).
 146    * The soft button effect is applied within the supplied rect region of the texture. Default values for this is (0.0, 0.0, 1.0, 1.0) which is the entire image with
 147    * 0,0 being the top left and 1.0, 1.0 being the bottom right. If the image texture is split between multiple ImageActors then the developer should specify the
 148    * pixel area of the texture the effect should be applied with. Example, If the Image is split among two ImageActors side by side, with the left one using left half of the
 149    * texture and right one using the right half of the texture then the pixel area value for the left ImageActor will be (0.0, 0.0, 0.5, 1.0) and the pixel area for the right
 150    * will be (0.5, 0.0, 1.0, 1.0).
 151    * @return A std::string containing the property name
 152    */
 153   const std::string& GetEffectPixelAreaPropertyName() const;
 154
 155   /**
 156    * Get the name for the rectangle size scale property (float). Only applicable having created this SoftButtonEffect via a call to New() with RECTANGULAR as the type.
 157    * This property can be used to set the mix between proportion of rectangle and proportion of ellipse - the result is a rectangle with rounded corners. If the value is 0.0,
 158    * the shape is an ellipse. If the value is close to 1.0, the shape is close to a rectangle. The value lies in the range [0.0 - 1.0). Note that a value of 1.0 is NOT allowed.
 159    * Default 0.5.
 160    * @return A std::string containing the property name
 161    */
 162   const std::string& GetRectangleSizeScalePropertyName() const;
 163
 164
 165 private:
 166   // Not intended for application developers
 167   SoftButtonEffect(ShaderEffect handle);
 168 };
 169
 170 }
 171
 172 }
 173
 174 #endif //#ifndef __DALI_TOOLKIT_SHADER_EFFECT_SOFT_BUTTON_H__
 175