3b783f6380d9f85035369de2110e845a5c89cb31
[platform/core/uifw/dali-toolkit.git] / 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