diff options
Diffstat (limited to 'site/user/api/SkPicture_Reference.md')
| -rw-r--r-- | site/user/api/SkPicture_Reference.md | 86 |
1 files changed, 49 insertions, 37 deletions
diff --git a/site/user/api/SkPicture_Reference.md b/site/user/api/SkPicture_Reference.md index 0992737b04..1d8c1bbc84 100644 --- a/site/user/api/SkPicture_Reference.md +++ b/site/user/api/SkPicture_Reference.md @@ -26,8 +26,16 @@ SkPicture can be constructed or initialized by these functions, including C++ cl </tr> </table> -An <a href='#SkPicture'>SkPicture</a> records drawing commands made to a canvas to be played back at a later time. -This base class handles serialization and a few other miscellany. +<a href='#Picture'>Picture</a> records drawing commands made to <a href='SkCanvas_Reference#Canvas'>Canvas</a>. The command stream may be +played in whole or in part at a later time. + +<a href='#Picture'>Picture</a> is an abstract class. <a href='#Picture'>Picture</a> may be generated by <a href='undocumented#Picture_Recorder'>Picture Recorder</a> +or <a href='undocumented#Drawable'>Drawable</a>, or from <a href='#Picture'>Picture</a> previously saved to <a href='undocumented#Data'>Data</a> or <a href='undocumented#Stream'>Stream</a>. + +<a href='#Picture'>Picture</a> may contain any <a href='SkCanvas_Reference#Canvas'>Canvas</a> drawing command, as well as one or more +<a href='SkCanvas_Reference#Matrix'>Canvas Matrix</a> or <a href='SkCanvas_Reference#Clip'>Canvas Clip</a>. <a href='#Picture'>Picture</a> has a cull <a href='SkRect_Reference#Rect'>Rect</a>, which is used as +a bounding box hint. To limit <a href='#Picture'>Picture</a> bounds, use <a href='SkCanvas_Reference#Clip'>Canvas Clip</a> when +recording or drawing <a href='#Picture'>Picture</a>. ## Overview @@ -134,13 +142,11 @@ SkPicture member functions read and modify the structure properties. virtual </pre> -<a href='undocumented#Subclasses'>Subclasses</a> of this can be passed to <a href='#SkPicture_playback'>playback</a>. During the playback -of the picture, this callback will periodically be invoked. If its -<a href='#SkPicture_AbortCallback_abort'>abort</a> returns true, then picture playback will be interrupted. -The resulting drawing is undefined, as there is no guarantee how often the -callback will be invoked. If the abort happens inside some level of nested -calls to save(), restore will automatically be called to return the state -to the same level it was before the playback call was made. +<a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> is an abstract class. An implementation of <a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> may +passed as a parameter to <a href='#SkPicture_playback'>SkPicture::playback</a>, to stop it before all drawing +commands have been processed. + +If <a href='#SkPicture_AbortCallback_abort'>AbortCallback::abort</a> returns true, <a href='#SkPicture_playback'>SkPicture::playback</a> is interrupted. <a name='SkPicture_AbortCallback_empty_constructor'></a> ## AbortCallback @@ -184,8 +190,14 @@ virtual bool <a href='#SkPicture_AbortCallback_abort'>abort</a>() = 0 </pre> Stops <a href='#Picture'>Picture</a> playback when some condition is met. A subclass of -<a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> provides an override for <a href='#SkPicture_AbortCallback_abort'>abort</a> that can stop <a href='#SkPicture_playback'>playback</a> from -drawing the entire picture. +<a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> provides an override for <a href='#SkPicture_AbortCallback_abort'>abort</a> that can stop <a href='#SkPicture_playback'>SkPicture::playback</a>. + +The part of <a href='#Picture'>Picture</a> drawn when aborted is undefined. <a href='#Picture'>Picture</a> instantiations are +free to stop drawing at different points during playback. + +If the abort happens inside one or more calls to <a href='SkCanvas_Reference#SkCanvas_save'>SkCanvas::save()</a>, stack +of <a href='SkCanvas_Reference#Matrix'>Canvas Matrix</a> and <a href='SkCanvas_Reference#Clip'>Canvas Clip</a> values is restored to its state before +<a href='#SkPicture_playback'>SkPicture::playback</a> was called. ### Return Value @@ -312,10 +324,11 @@ Recreates a picture that was serialized into <a href='#SkPicture_MakeFromData_2_ virtual void <a href='#SkPicture_playback'>playback</a>(<a href='SkCanvas_Reference#SkCanvas'>SkCanvas</a>* canvas, <a href='#SkPicture_AbortCallback'>AbortCallback</a>* callback = nullptr) const = 0 </pre> -Replays the drawing commands on the specified <a href='#SkPicture_playback_canvas'>canvas</a>. Note that -this has the effect of unfurling this picture into the destination -<a href='#SkPicture_playback_canvas'>canvas</a>. Using the <a href='SkCanvas_Reference#SkCanvas_drawPicture'>SkCanvas::drawPicture</a> entry point gives the destination -<a href='#SkPicture_playback_canvas'>canvas</a> the option of just taking a ref. +Replays the drawing commands on the specified <a href='#SkPicture_playback_canvas'>canvas</a>. In the case that the +commands are recorded, each command in the <a href='#Picture'>Picture</a> is sent separately to <a href='#SkPicture_playback_canvas'>canvas</a>. + +To add a single command to draw <a href='#Picture'>Picture</a> to recording <a href='#SkPicture_playback_canvas'>canvas</a>, call +<a href='SkCanvas_Reference#SkCanvas_drawPicture'>SkCanvas::drawPicture</a> instead. ### Parameters @@ -344,8 +357,12 @@ this has the effect of unfurling this picture into the destination virtual <a href='SkRect_Reference#SkRect'>SkRect</a> <a href='#SkPicture_cullRect'>cullRect</a>() const = 0 </pre> -Returns cull <a href='SkRect_Reference#Rect'>Rect</a> for this picture. -Ops recorded into this picture that attempt to draw outside the cull might not be drawn. +Returns cull <a href='SkRect_Reference#Rect'>Rect</a> for this picture, passed in when <a href='#Picture'>Picture</a> was created. +Returned <a href='SkRect_Reference#Rect'>Rect</a> does not specify clipping <a href='SkRect_Reference#Rect'>Rect</a> for <a href='#Picture'>Picture</a>; cull is hint +of <a href='#Picture'>Picture</a> bounds. + +<a href='#Picture'>Picture</a> is free to discard recorded drawing commands that fall outside +cull. ### Return Value @@ -370,7 +387,7 @@ bounds may be drawn, and are drawn in this example. uint32_t <a href='#SkPicture_uniqueID'>uniqueID</a>() const </pre> -Returns a non-zero value unique among all pictures. +Returns a non-zero value unique among <a href='#Picture'>Pictures</a> in Skia process. ### Return Value @@ -402,7 +419,8 @@ placeholder id = 2 <a href='undocumented#sk_sp'>sk sp</a><<a href='undocumented#SkData'>SkData</a>> <a href='#SkPicture_serialize'>serialize</a>(const <a href='undocumented#SkSerialProcs'>SkSerialProcs</a>* procs = nullptr) const </pre> -Returns storage containing data describing <a href='#Picture'>Picture</a>, using optional custom encoders. +Returns storage containing data describing <a href='#Picture'>Picture</a>, using optional custom +encoders. ### Parameters @@ -460,9 +478,12 @@ Writes picture to <a href='#SkPicture_serialize_2_stream'>stream</a>, using opti static <a href='undocumented#sk_sp'>sk sp</a><<a href='#SkPicture'>SkPicture</a>> <a href='#SkPicture_MakePlaceholder'>MakePlaceholder</a>(<a href='SkRect_Reference#SkRect'>SkRect</a> cull) </pre> -Returns a placeholder <a href='#SkPicture'>SkPicture</a>. -This placeholder does not draw anything itself. It has a distinct <a href='#SkPicture_uniqueID'>uniqueID</a> -(just like all <a href='#Picture'>Pictures</a>) and will always be visible to <a href='undocumented#SkSerialProcs'>SkSerialProcs</a>. +Returns a placeholder <a href='#SkPicture'>SkPicture</a>. Result does not draw, and contains only +<a href='#SkPicture_MakePlaceholder_cull'>cull</a> <a href='SkRect_Reference#Rect'>Rect</a>, a hint of its bounds. Result is immutable; it cannot be changed +later. Result identifier is unique. + +Returned placeholder can be intercepted during playback to insert other +commands into <a href='SkCanvas_Reference#Canvas'>Canvas</a> draw stream. ### Parameters @@ -477,20 +498,11 @@ placeholder with unique identifier ### Example -<div><fiddle-embed name="32f84819483a906ede9c5525801845ef"> - -#### Example Output - -~~~~ -id:1 bounds:{10, 40, 80, 110} -id:2 bounds:{10, 40, 80, 110} -~~~~ - -</fiddle-embed></div> +<div><fiddle-embed name="0d2cbf82f490ffb180e0b4531afa232c"></fiddle-embed></div> ### See Also -<a href='#SkPicture_MakeFromStream'>MakeFromStream</a> <a href='#SkPicture_MakeFromData'>MakeFromData</a><sup><a href='#SkPicture_MakeFromData_2'>[2]</a></sup> +<a href='#SkPicture_MakeFromStream'>MakeFromStream</a> <a href='#SkPicture_MakeFromData'>MakeFromData</a><sup><a href='#SkPicture_MakeFromData_2'>[2]</a></sup> <a href='#SkPicture_uniqueID'>uniqueID</a> --- @@ -501,9 +513,9 @@ id:2 bounds:{10, 40, 80, 110} virtual int <a href='#SkPicture_approximateOpCount'>approximateOpCount</a>() const = 0 </pre> -Returns the approximate number of operations in this picture. This -number may be greater or less than the number of <a href='SkCanvas_Reference#SkCanvas'>SkCanvas</a> calls -recorded: some calls may be recorded as more than one operation, or some +Returns the approximate number of operations in <a href='#Picture'>Picture</a>. Returned value +may be greater or less than the number of <a href='SkCanvas_Reference#SkCanvas'>SkCanvas</a> calls +recorded: some calls may be recorded as more than one operation, other calls may be optimized away. ### Return Value @@ -528,7 +540,7 @@ virtual size_t <a href='#SkPicture_approximateBytesUsed'>approximateBytesUsed</a </pre> Returns the approximate byte size of <a href='#Picture'>Picture</a>. Does not include large objects -referenced <a href='#Picture'>Picture</a>. +referenced by <a href='#Picture'>Picture</a>. ### Return Value |