1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/gfx/skia/trunk/include/animator/SkAnimator.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,500 @@
1.4 +
1.5 +/*
1.6 + * Copyright 2006 The Android Open Source Project
1.7 + *
1.8 + * Use of this source code is governed by a BSD-style license that can be
1.9 + * found in the LICENSE file.
1.10 + */
1.11 +
1.12 +
1.13 +#ifndef SkAnimator_DEFINED
1.14 +#define SkAnimator_DEFINED
1.15 +
1.16 +#include "SkScalar.h"
1.17 +#include "SkKey.h"
1.18 +#include "SkEventSink.h"
1.19 +
1.20 +class SkAnimateMaker;
1.21 +class SkCanvas;
1.22 +class SkDisplayable;
1.23 +class SkEvent;
1.24 +class SkExtras;
1.25 +struct SkMemberInfo;
1.26 +class SkPaint;
1.27 +struct SkRect;
1.28 +class SkStream;
1.29 +class SkTypedArray;
1.30 +class SkXMLParserError;
1.31 +class SkDOM;
1.32 +struct SkDOMNode;
1.33 +
1.34 +/** SkElementType is the type of element: a rectangle, a color, an animator, and so on.
1.35 + This enum is incomplete and will be fleshed out in a future release */
1.36 +enum SkElementType {
1.37 + kElementDummyType
1.38 +};
1.39 +/** SkFieldType is the type of field: a scalar, a string, an integer, a boolean, and so on.
1.40 + This enum is incomplete and will be fleshed out in a future release */
1.41 +enum SkFieldType {
1.42 + kFieldDummyType
1.43 +};
1.44 +
1.45 +/** \class SkAnimator
1.46 +
1.47 + The SkAnimator class decodes an XML stream into a display list. The
1.48 + display list can be drawn statically as a picture, or can drawn
1.49 + different elements at different times to form a moving animation.
1.50 +
1.51 + SkAnimator does not read the system time on its own; it relies on the
1.52 + caller to pass the current time. The caller can pause, speed up, or
1.53 + reverse the animation by varying the time passed in.
1.54 +
1.55 + The XML describing the display list must conform to the schema
1.56 + described by SkAnimateSchema.xsd.
1.57 +
1.58 + The XML must contain an <event> element to draw. Usually, it contains
1.59 + an <event kind="onload" /> block to add some drawing elements to the
1.60 + display list when the document is first decoded.
1.61 +
1.62 + Here's an "Hello World" XML sample:
1.63 +
1.64 + <screenplay>
1.65 + <event kind="onload" >
1.66 + <text text="Hello World" y="20" />
1.67 + </event>
1.68 + </screenplay>
1.69 +
1.70 + To read and draw this sample:
1.71 +
1.72 + // choose one of these two
1.73 + SkAnimator animator; // declare an animator instance on the stack
1.74 + // SkAnimator* animator = new SkAnimator() // or one could instantiate the class
1.75 +
1.76 + // choose one of these three
1.77 + animator.decodeMemory(buffer, size); // to read from RAM
1.78 + animator.decodeStream(stream); // to read from a user-defined stream (e.g., a zip file)
1.79 + animator.decodeURI(filename); // to read from a web location, or from a local text file
1.80 +
1.81 + // to draw to the current window:
1.82 + SkCanvas canvas(getBitmap()); // create a canvas
1.83 + animator.draw(canvas, &paint, 0); // draw the scene
1.84 +*/
1.85 +class SkAnimator : public SkEventSink {
1.86 +public:
1.87 + SkAnimator();
1.88 + virtual ~SkAnimator();
1.89 +
1.90 + /** Add a drawable extension to the graphics engine. Experimental.
1.91 + @param extras A derived class that implements methods that identify and instantiate the class
1.92 + */
1.93 + void addExtras(SkExtras* extras);
1.94 +
1.95 + /** Read in XML from a stream, and append it to the current
1.96 + animator. Returns false if an error was encountered.
1.97 + Error diagnostics are stored in fErrorCode and fLineNumber.
1.98 + @param stream The stream to append.
1.99 + @return true if the XML was parsed successfully.
1.100 + */
1.101 + bool appendStream(SkStream* stream);
1.102 +
1.103 + /** Read in XML from memory. Returns true if the file can be
1.104 + read without error. Returns false if an error was encountered.
1.105 + Error diagnostics are stored in fErrorCode and fLineNumber.
1.106 + @param buffer The XML text as UTF-8 characters.
1.107 + @param size The XML text length in bytes.
1.108 + @return true if the XML was parsed successfully.
1.109 + */
1.110 + bool decodeMemory(const void* buffer, size_t size);
1.111 +
1.112 + /** Read in XML from a stream. Returns true if the file can be
1.113 + read without error. Returns false if an error was encountered.
1.114 + Error diagnostics are stored in fErrorCode and fLineNumber.
1.115 + @param stream The stream containg the XML text as UTF-8 characters.
1.116 + @return true if the XML was parsed successfully.
1.117 + */
1.118 + virtual bool decodeStream(SkStream* stream);
1.119 +
1.120 + /** Parse the DOM tree starting at the specified node. Returns true if it can be
1.121 + parsed without error. Returns false if an error was encountered.
1.122 + Error diagnostics are stored in fErrorCode and fLineNumber.
1.123 + @return true if the DOM was parsed successfully.
1.124 + */
1.125 + virtual bool decodeDOM(const SkDOM&, const SkDOMNode*);
1.126 +
1.127 + /** Read in XML from a URI. Returns true if the file can be
1.128 + read without error. Returns false if an error was encountered.
1.129 + Error diagnostics are stored in fErrorCode and fLineNumber.
1.130 + @param uri The complete url path to be read (either ftp, http or https).
1.131 + @return true if the XML was parsed successfully.
1.132 + */
1.133 + bool decodeURI(const char uri[]);
1.134 +
1.135 + /** Pass a char event, usually a keyboard symbol, to the animator.
1.136 + This triggers events of the form <event kind="keyChar" key="... />
1.137 + @param ch The character to match against <event> element "key"
1.138 + attributes.
1.139 + @return true if the event was dispatched successfully.
1.140 + */
1.141 + bool doCharEvent(SkUnichar ch);
1.142 +
1.143 + /** Experimental:
1.144 + Pass a mouse click event along with the mouse coordinates to
1.145 + the animator. This triggers events of the form <event kind="mouseDown" ... />
1.146 + and other mouse events.
1.147 + @param state The mouse state, described by SkView::Click::State : values are
1.148 + down == 0, moved == 1, up == 2
1.149 + @param x The x-position of the mouse
1.150 + @param y The y-position of the mouse
1.151 + @return true if the event was dispatched successfully.
1.152 + */
1.153 + bool doClickEvent(int state, SkScalar x, SkScalar y);
1.154 +
1.155 + /** Pass a meta-key event, such as an arrow , to the animator.
1.156 + This triggers events of the form <event kind="keyPress" code="... />
1.157 + @param code The key to match against <event> element "code"
1.158 + attributes.
1.159 + @return true if the event was dispatched successfully.
1.160 + */
1.161 + bool doKeyEvent(SkKey code);
1.162 + bool doKeyUpEvent(SkKey code);
1.163 +
1.164 + /** Send an event to the animator. The animator's clock is set
1.165 + relative to the current time.
1.166 + @return true if the event was dispatched successfully.
1.167 + */
1.168 + bool doUserEvent(const SkEvent& evt);
1.169 +
1.170 + /** The possible results from the draw function.
1.171 + */
1.172 + enum DifferenceType {
1.173 + kNotDifferent,
1.174 + kDifferent,
1.175 + kPartiallyDifferent
1.176 + };
1.177 + /** Draws one frame of the animation. The first call to draw always
1.178 + draws the initial frame of the animation. Subsequent calls draw
1.179 + the offset into the animation by
1.180 + subtracting the initial time from the current time.
1.181 + @param canvas The canvas to draw into.
1.182 + @param paint The paint to draw with.
1.183 + @param time The offset into the current animation.
1.184 + @return kNotDifferent if there are no active animations; kDifferent if there are active animations; and
1.185 + kPartiallyDifferent if the document contains an active <bounds> element that specifies a minimal
1.186 + redraw area.
1.187 + */
1.188 + DifferenceType draw(SkCanvas* canvas, SkPaint* paint, SkMSec time);
1.189 +
1.190 + /** Draws one frame of the animation, using a new Paint each time.
1.191 + The first call to draw always
1.192 + draws the initial frame of the animation. Subsequent calls draw
1.193 + the offset into the animation by
1.194 + subtracting the initial time from the current time.
1.195 + @param canvas The canvas to draw into.
1.196 + @param time The offset into the current animation.
1.197 + @return kNotDifferent if there are no active animations; kDifferent if there are active animations; and
1.198 + kPartiallyDifferent if the document contains an active <bounds> element that specifies a minimal
1.199 + redraw area.
1.200 + */
1.201 + DifferenceType draw(SkCanvas* canvas, SkMSec time);
1.202 +
1.203 + /** Experimental:
1.204 + Helper to choose whether to return a SkView::Click handler.
1.205 + @param x ignored
1.206 + @param y ignored
1.207 + @return true if a mouseDown event handler is enabled.
1.208 + */
1.209 + bool findClickEvent(SkScalar x, SkScalar y);
1.210 +
1.211 +
1.212 + /** Get the nested animator associated with this element, if any.
1.213 + Use this to access a movie's event sink, to send events to movies.
1.214 + @param element the value returned by getElement
1.215 + @return the internal animator.
1.216 + */
1.217 + const SkAnimator* getAnimator(const SkDisplayable* element) const;
1.218 +
1.219 + /** Returns the scalar value of the specified element's attribute[index]
1.220 + @param element the value returned by getElement
1.221 + @param field the value returned by getField
1.222 + @param index the array entry
1.223 + @return the integer value to retrieve, or SK_NaN32 if unsuccessful
1.224 + */
1.225 + int32_t getArrayInt(const SkDisplayable* element, const SkMemberInfo* field, int index);
1.226 +
1.227 + /** Returns the scalar value of the specified element's attribute[index]
1.228 + @param elementID is the value of the id attribute in the XML of this element
1.229 + @param fieldName specifies the name of the attribute
1.230 + @param index the array entry
1.231 + @return the integer value to retrieve, or SK_NaN32 if unsuccessful
1.232 + */
1.233 + int32_t getArrayInt(const char* elementID, const char* fieldName, int index);
1.234 +
1.235 + /** Returns the scalar value of the specified element's attribute[index]
1.236 + @param element the value returned by getElement
1.237 + @param field the value returned by getField
1.238 + @param index the array entry
1.239 + @return the scalar value to retrieve, or SK_ScalarNaN if unsuccessful
1.240 + */
1.241 + SkScalar getArrayScalar(const SkDisplayable* element, const SkMemberInfo* field, int index);
1.242 +
1.243 + /** Returns the scalar value of the specified element's attribute[index]
1.244 + @param elementID is the value of the id attribute in the XML of this element
1.245 + @param fieldName specifies the name of the attribute
1.246 + @param index the array entry
1.247 + @return the scalar value to retrieve, or SK_ScalarNaN if unsuccessful
1.248 + */
1.249 + SkScalar getArrayScalar(const char* elementID, const char* fieldName, int index);
1.250 +
1.251 + /** Returns the string value of the specified element's attribute[index]
1.252 + @param element is a value returned by getElement
1.253 + @param field is a value returned by getField
1.254 + @param index the array entry
1.255 + @return the string value to retrieve, or null if unsuccessful
1.256 + */
1.257 + const char* getArrayString(const SkDisplayable* element, const SkMemberInfo* field, int index);
1.258 +
1.259 + /** Returns the string value of the specified element's attribute[index]
1.260 + @param elementID is the value of the id attribute in the XML of this element
1.261 + @param fieldName specifies the name of the attribute
1.262 + @param index the array entry
1.263 + @return the string value to retrieve, or null if unsuccessful
1.264 + */
1.265 + const char* getArrayString(const char* elementID, const char* fieldName, int index);
1.266 +
1.267 + /** Returns the XML element corresponding to the given ID.
1.268 + @param elementID is the value of the id attribute in the XML of this element
1.269 + @return the element matching the ID, or null if the element can't be found
1.270 + */
1.271 + const SkDisplayable* getElement(const char* elementID);
1.272 +
1.273 + /** Returns the element type corresponding to the XML element.
1.274 + The element type matches the element name; for instance, <line> returns kElement_LineType
1.275 + @param element is a value returned by getElement
1.276 + @return element type, or 0 if the element can't be found
1.277 + */
1.278 + SkElementType getElementType(const SkDisplayable* element);
1.279 +
1.280 + /** Returns the element type corresponding to the given ID.
1.281 + @param elementID is the value of the id attribute in the XML of this element
1.282 + @return element type, or 0 if the element can't be found
1.283 + */
1.284 + SkElementType getElementType(const char* elementID);
1.285 +
1.286 + /** Returns the XML field of the named attribute in the XML element.
1.287 + @param element is a value returned by getElement
1.288 + @param fieldName is the attribute to return
1.289 + @return the attribute matching the fieldName, or null if the element can't be found
1.290 + */
1.291 + const SkMemberInfo* getField(const SkDisplayable* element, const char* fieldName);
1.292 +
1.293 + /** Returns the XML field of the named attribute in the XML element matching the elementID.
1.294 + @param elementID is the value of the id attribute in the XML of this element
1.295 + @param fieldName is the attribute to return
1.296 + @return the attribute matching the fieldName, or null if the element can't be found
1.297 + */
1.298 + const SkMemberInfo* getField(const char* elementID, const char* fieldName);
1.299 +
1.300 + /** Returns the value type coresponding to the element's attribute.
1.301 + The value type matches the XML schema: and may be kField_BooleanType, kField_ScalarType, etc.
1.302 + @param field is a value returned by getField
1.303 + @return the attribute type, or 0 if the element can't be found
1.304 + */
1.305 + SkFieldType getFieldType(const SkMemberInfo* field);
1.306 +
1.307 + /** Returns the value type coresponding to the element's attribute.
1.308 + @param elementID is the value of the id attribute in the XML of this element
1.309 + @param fieldName specifies the name of the attribute
1.310 + @return the attribute type, or 0 if the element can't be found
1.311 + */
1.312 + SkFieldType getFieldType(const char* elementID, const char* fieldName);
1.313 +
1.314 + /** Returns the recommended animation interval. Returns zero if no
1.315 + interval is specified.
1.316 + */
1.317 + SkMSec getInterval();
1.318 +
1.319 + /** Returns the partial rectangle to invalidate after drawing. Call after draw() returns
1.320 + kIsPartiallyDifferent to do a mimimal inval(). */
1.321 + void getInvalBounds(SkRect* inval);
1.322 +
1.323 + /** Returns the details of any error encountered while parsing the XML.
1.324 + */
1.325 + const SkXMLParserError* getParserError();
1.326 +
1.327 + /** Returns the details of any error encountered while parsing the XML as string.
1.328 + */
1.329 + const char* getParserErrorString();
1.330 +
1.331 + /** Returns the scalar value of the specified element's attribute
1.332 + @param element is a value returned by getElement
1.333 + @param field is a value returned by getField
1.334 + @return the integer value to retrieve, or SK_NaN32 if not found
1.335 + */
1.336 + int32_t getInt(const SkDisplayable* element, const SkMemberInfo* field);
1.337 +
1.338 + /** Returns the scalar value of the specified element's attribute
1.339 + @param elementID is the value of the id attribute in the XML of this element
1.340 + @param fieldName specifies the name of the attribute
1.341 + @return the integer value to retrieve, or SK_NaN32 if not found
1.342 + */
1.343 + int32_t getInt(const char* elementID, const char* fieldName);
1.344 +
1.345 + /** Returns the scalar value of the specified element's attribute
1.346 + @param element is a value returned by getElement
1.347 + @param field is a value returned by getField
1.348 + @return the scalar value to retrieve, or SK_ScalarNaN if not found
1.349 + */
1.350 + SkScalar getScalar(const SkDisplayable* element, const SkMemberInfo* field);
1.351 +
1.352 + /** Returns the scalar value of the specified element's attribute
1.353 + @param elementID is the value of the id attribute in the XML of this element
1.354 + @param fieldName specifies the name of the attribute
1.355 + @return the scalar value to retrieve, or SK_ScalarNaN if not found
1.356 + */
1.357 + SkScalar getScalar(const char* elementID, const char* fieldName);
1.358 +
1.359 + /** Returns the string value of the specified element's attribute
1.360 + @param element is a value returned by getElement
1.361 + @param field is a value returned by getField
1.362 + @return the string value to retrieve, or null if not found
1.363 + */
1.364 + const char* getString(const SkDisplayable* element, const SkMemberInfo* field);
1.365 +
1.366 + /** Returns the string value of the specified element's attribute
1.367 + @param elementID is the value of the id attribute in the XML of this element
1.368 + @param fieldName specifies the name of the attribute
1.369 + @return the string value to retrieve, or null if not found
1.370 + */
1.371 + const char* getString(const char* elementID, const char* fieldName);
1.372 +
1.373 + /** Gets the file default directory of the URL base path set explicitly or by reading the last URL. */
1.374 + const char* getURIBase();
1.375 +
1.376 + /** Resets the animator to a newly created state with no animation data. */
1.377 + void initialize();
1.378 +
1.379 + /** Experimental. Resets any active animations so that the next time passed is treated as
1.380 + time zero. */
1.381 + void reset();
1.382 +
1.383 + /** Sets the scalar value of the specified element's attribute
1.384 + @param elementID is the value of the id attribute in the XML of this element
1.385 + @param fieldName specifies the name of the attribute
1.386 + @param array is the c-style array of integers
1.387 + @param count is the length of the array
1.388 + @return true if the value was set successfully
1.389 + */
1.390 + bool setArrayInt(const char* elementID, const char* fieldName, const int* array, int count);
1.391 +
1.392 + /** Sets the scalar value of the specified element's attribute
1.393 + @param elementID is the value of the id attribute in the XML of this element
1.394 + @param fieldName specifies the name of the attribute
1.395 + @param array is the c-style array of strings
1.396 + @param count is the length of the array
1.397 + @return true if the value was set successfully
1.398 + */
1.399 + bool setArrayString(const char* elementID, const char* fieldName, const char** array, int count);
1.400 +
1.401 + /** Sets the scalar value of the specified element's attribute
1.402 + @param elementID is the value of the id attribute in the XML of this element
1.403 + @param fieldName specifies the name of the attribute
1.404 + @param data the integer value to set
1.405 + @return true if the value was set successfully
1.406 + */
1.407 + bool setInt(const char* elementID, const char* fieldName, int32_t data);
1.408 +
1.409 + /** Sets the scalar value of the specified element's attribute
1.410 + @param elementID is the value of the id attribute in the XML of this element
1.411 + @param fieldName specifies the name of the attribute
1.412 + @param data the scalar value to set
1.413 + @return true if the value was set successfully
1.414 + */
1.415 + bool setScalar(const char* elementID, const char* fieldName, SkScalar data);
1.416 +
1.417 + /** Sets the string value of the specified element's attribute
1.418 + @param elementID is the value of the id attribute in the XML of this element
1.419 + @param fieldName specifies the name of the attribute
1.420 + @param data the string value to set
1.421 + @return true if the value was set successfully
1.422 + */
1.423 + bool setString(const char* elementID, const char* fieldName, const char* data);
1.424 +
1.425 + /** Sets the file default directory of the URL base path
1.426 + @param path the directory path
1.427 + */
1.428 + void setURIBase(const char* path);
1.429 +
1.430 + typedef void* Handler;
1.431 + // This guy needs to be exported to java, so don't make it virtual
1.432 + void setHostHandler(Handler handler) {
1.433 + this->onSetHostHandler(handler);
1.434 + }
1.435 +
1.436 + /** \class Timeline
1.437 + Returns current time to animator. To return a custom timeline, create a child
1.438 + class and override the getMSecs method.
1.439 + */
1.440 + class Timeline {
1.441 + public:
1.442 + virtual ~Timeline() {}
1.443 +
1.444 + /** Returns the current time in milliseconds */
1.445 + virtual SkMSec getMSecs() const = 0;
1.446 + };
1.447 +
1.448 + /** Sets a user class to return the current time to the animator.
1.449 + Optional; if not called, the system clock will be used by calling SkTime::GetMSecs instead.
1.450 + @param callBack the time function
1.451 + */
1.452 + void setTimeline(const Timeline& );
1.453 +
1.454 + static void Init(bool runUnitTests);
1.455 + static void Term();
1.456 +
1.457 + /** The event sink events generated by the animation are posted to.
1.458 + Screenplay also posts an inval event to this event sink after processing an
1.459 + event to force a redraw.
1.460 + @param target the event sink id
1.461 + */
1.462 + void setHostEventSinkID(SkEventSinkID hostID);
1.463 + SkEventSinkID getHostEventSinkID() const;
1.464 +
1.465 + // helper
1.466 + void setHostEventSink(SkEventSink* sink) {
1.467 + this->setHostEventSinkID(sink ? sink->getSinkID() : 0);
1.468 + }
1.469 +
1.470 + virtual void setJavaOwner(Handler owner);
1.471 +
1.472 +#ifdef SK_DEBUG
1.473 + virtual void eventDone(const SkEvent& evt);
1.474 + virtual bool isTrackingEvents();
1.475 + static bool NoLeaks();
1.476 +#endif
1.477 +
1.478 +protected:
1.479 + virtual void onSetHostHandler(Handler handler);
1.480 + virtual void onEventPost(SkEvent*, SkEventSinkID);
1.481 + virtual void onEventPostTime(SkEvent*, SkEventSinkID, SkMSec time);
1.482 +
1.483 +private:
1.484 +// helper functions for setters
1.485 + bool setArray(SkDisplayable* element, const SkMemberInfo* field, SkTypedArray array);
1.486 + bool setArray(const char* elementID, const char* fieldName, SkTypedArray array);
1.487 + bool setInt(SkDisplayable* element, const SkMemberInfo* field, int32_t data);
1.488 + bool setScalar(SkDisplayable* element, const SkMemberInfo* field, SkScalar data);
1.489 + bool setString(SkDisplayable* element, const SkMemberInfo* field, const char* data);
1.490 +
1.491 + virtual bool onEvent(const SkEvent&);
1.492 + SkAnimateMaker* fMaker;
1.493 + friend class SkAnimateMaker;
1.494 + friend class SkAnimatorScript;
1.495 + friend class SkAnimatorScript2;
1.496 + friend class SkApply;
1.497 + friend class SkDisplayMovie;
1.498 + friend class SkDisplayType;
1.499 + friend class SkPost;
1.500 + friend class SkXMLAnimatorWriter;
1.501 +};
1.502 +
1.503 +#endif
