// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef PPAPI_UTILITY_GRAPHICS_PAINT_MANAGER_H_
#define PPAPI_UTILITY_GRAPHICS_PAINT_MANAGER_H_
#include <vector>
#include "ppapi/cpp/graphics_2d.h"
#include "ppapi/utility/completion_callback_factory.h"
#include "ppapi/utility/graphics/paint_aggregator.h"
/// @file
/// This file defines the API to convert the "plugin push" model of painting
/// in PPAPI to a paint request at a later time.
namespace pp {
class Graphics2D;
class Instance;
class Point;
class Rect;
/// This class converts the "instance push" model of painting in PPAPI to a
/// paint request at a later time. Usage is that you call Invalidate and
/// Scroll, and implement the Client interface. Your OnPaint handler will
/// then get called with coalesced paint events.
///
/// This class is basically a <code>PaintAggregator</code> that groups updates,
/// plus management of callbacks for scheduling paints.
///
/// <strong>Example:</strong>
///
/// <code>
///
/// class MyClass : public pp::Instance, public PaintManager::Client {
/// public:
/// MyClass() {
/// paint_manager_.Initialize(this, this, false);
/// }
///
/// void ViewChanged(const pp::Rect& position, const pp::Rect& clip) {
/// paint_manager_.SetSize(position.size());
/// }
///
/// void DoSomething() {
/// // This function does something like respond to an event that causes
/// // the screen to need updating.
/// paint_manager_.InvalidateRect(some_rect);
/// }
///
/// // Implementation of PaintManager::Client
/// virtual bool OnPaint(pp::Graphics2D& device,
/// const pp::PaintUpdate& update) {
/// // If our app needed scrolling, we would apply that first here.
///
/// // Then we would either repaint the area returned by GetPaintBounds or
/// // iterate through all the paint_rects.
///
/// // The caller will call Flush() for us, so don't do that here.
/// return true;
/// }
///
/// private:
/// pp::PaintManager paint_manager_;
/// };
/// </code>
class PaintManager {
public:
class Client {
public:
/// OnPaint() paints the given invalid area of the instance to the given
/// graphics device. Returns true if anything was painted.
///
/// You are given the list of rects to paint in <code>paint_rects</code>,
/// and the union of all of these rects in <code>paint_bounds</code>. You
/// only have to paint the area inside each of the
/// <code>paint_rects</code>, but can paint more if you want (some apps may
/// just want to paint the union).
///
/// Do not call Flush() on the graphics device, this will be done
/// automatically if you return true from this function since the
/// <code>PaintManager</code> needs to handle the callback.
///
/// It is legal for you to cause invalidates inside of Paint which will
/// then get executed as soon as the Flush for this update has completed.
/// However, this is not very nice to the host system since it will spin the
/// CPU, possibly updating much faster than necessary. It is best to have a
/// 1/60 second timer to do an invalidate instead. This will limit your
/// animation to the slower of 60Hz or "however fast Flush can complete."
///
/// @param[in] graphics A <code>Graphics2D</code> to be painted.
/// @param[in] paint_rects A list of rects to paint.
/// @param[in] paint_bounds A union of the rects to paint.
///
/// @return true if successful, otherwise false.
virtual bool OnPaint(Graphics2D& graphics,
const std::vector<Rect>& paint_rects,
const Rect& paint_bounds) = 0;
protected:
// You shouldn't be doing deleting through this interface.
virtual ~Client() {}
};
/// Default constructor for creating an is_null() <code>PaintManager</code>
/// object. If you use this version of the constructor, you must call
/// Initialize() below.
PaintManager();
/// A constructor to create a new <code>PaintManager</code> with an instance
/// and client.
///
/// <strong>Note:</strong> You will need to call SetSize() before this class
/// will do anything. Normally you do this from the <code>ViewChanged</code>
/// method of your instance.
///
/// @param instance The instance using this paint manager to do its
/// painting. Painting will automatically go to this instance and you don't
/// have to manually bind any device context (this is all handled by the
/// paint manager).
///
/// @param client A non-owning pointer and must remain valid (normally the
/// object implementing the Client interface will own the paint manager).
///
/// @param is_always_opaque A flag passed to the device contexts that this
/// class creates. Set this to true if your instance always draws an opaque
/// image to the device. This is used as a hint to the browser that it does
/// not need to do alpha blending, which speeds up painting. If you generate
/// non-opqaue pixels or aren't sure, set this to false for more general
/// blending.
///
/// If you set is_always_opaque, your alpha channel should always be set to
/// 0xFF or there may be painting artifacts. Being opaque will allow the
/// browser to do a memcpy rather than a blend to paint the plugin, and this
/// means your alpha values will get set on the page backing store. If these
/// values are incorrect, it could mess up future blending. If you aren't
/// sure, it is always correct to specify that it it not opaque.
PaintManager(Instance* instance, Client* client, bool is_always_opaque);
/// Destructor.
~PaintManager();
/// Initialize() must be called if you are using the 0-arg constructor.
///
/// @param instance The instance using this paint manager to do its
/// painting. Painting will automatically go to this instance and you don't
/// have to manually bind any device context (this is all handled by the
/// paint manager).
/// @param client A non-owning pointer and must remain valid (normally the
/// object implementing the Client interface will own the paint manager).
/// @param is_always_opaque A flag passed to the device contexts that this
/// class creates. Set this to true if your instance always draws an opaque
/// image to the device. This is used as a hint to the browser that it does
/// not need to do alpha blending, which speeds up painting. If you generate
/// non-opqaue pixels or aren't sure, set this to false for more general
/// blending.
///
/// If you set <code>is_always_opaque</code>, your alpha channel should
/// always be set to <code>0xFF</code> or there may be painting artifacts.
/// Being opaque will allow the browser to do a memcpy rather than a blend
/// to paint the plugin, and this means your alpha values will get set on the
/// page backing store. If these values are incorrect, it could mess up
/// future blending. If you aren't sure, it is always correct to specify that
/// it it not opaque.
void Initialize(Instance* instance, Client* client, bool is_always_opaque);
/// Setter function setting the max ratio of paint rect area to scroll rect
/// area that we will tolerate before downgrading the scroll into a repaint.
///
/// If the combined area of paint rects contained within the scroll
/// rect grows too large, then we might as well just treat
/// the scroll rect as a paint rect.
///
/// @param[in] area The max ratio of paint rect area to scroll rect area that
/// we will tolerate before downgrading the scroll into a repaint.
void set_max_redundant_paint_to_scroll_area(float area) {
aggregator_.set_max_redundant_paint_to_scroll_area(area);
}
/// Setter function for setting the maximum number of paint rects. If we
/// exceed this limit, then we'll start combining paint rects (refer to
/// CombinePaintRects() for further information). This limiting can be
/// important since there is typically some overhead in deciding what to
/// paint. If your module is fast at doing these computations, raise this
/// threshold, if your module is slow, lower it (probably requires some
/// tuning to find the right value).
///
/// @param[in] max_rects The maximum number of paint rects.
void set_max_paint_rects(size_t max_rects) {
aggregator_.set_max_paint_rects(max_rects);
}
/// SetSize() sets the size of the instance. If the size is the same as the
/// previous call, this will be a NOP. If the size has changed, a new device
/// will be allocated to the given size and a paint to that device will be
/// scheduled.
///
/// This function is intended to be called from <code>ViewChanged</code> with
/// the size of the instance. Since it tracks the old size and only allocates
/// when the size changes, you can always call this function without worrying
/// about whether the size changed or ViewChanged() is called for another
/// reason (like the position changed).
///
/// @param new_size The new size for the instance.
void SetSize(const Size& new_size);
/// This function provides access to the underlying device in case you need
/// it. If you have done a SetSize(), note that the graphics context won't be
/// updated until right before the next call to OnPaint().
///
/// <strong>Note:</strong> If you call Flush on this device the paint manager
/// will get very confused, don't do this!
const Graphics2D& graphics() const { return graphics_; }
/// This function provides access to the underlying device in case you need
/// it. If you have done a SetSize(), note that the graphics context won't be
/// updated until right before the next call to OnPaint().
///
/// <strong>Note:</strong> If you call Flush on this device the paint manager
/// will get very confused, don't do this!
Graphics2D& graphics() { return graphics_; }
/// Invalidate() invalidate the entire instance.
void Invalidate();
/// InvalidateRect() Invalidate the provided rect.
///
/// @param[in] rect The <code>Rect</code> to be invalidated.
void InvalidateRect(const Rect& rect);
/// ScrollRect() scrolls the provided <code>clip_rect</code> by the
/// <code>amount</code> argument.
///
/// @param clip_rect The clip rectangle to scroll.
/// @param amount The amount to scroll <code>clip_rect</code>.
void ScrollRect(const Rect& clip_rect, const Point& amount);
/// GetEffectiveSize() returns the size of the graphics context for the
/// next paint operation. This is the pending size if a resize is pending
/// (the instance has called SetSize() but we haven't actually painted it
/// yet), or the current size of no resize is pending.
///
/// @return The effective size.
Size GetEffectiveSize() const;
private:
// Disallow copy and assign (these are unimplemented).
PaintManager(const PaintManager&);
PaintManager& operator=(const PaintManager&);
// Makes sure there is a callback that will trigger a paint at a later time.
// This will be either a Flush callback telling us we're allowed to generate
// more data, or, if there's no flush callback pending, a manual call back
// to the message loop via ExecuteOnMainThread.
void EnsureCallbackPending();
// Does the client paint and executes a Flush if necessary.
void DoPaint();
// Callback for asynchronous completion of Flush.
void OnFlushComplete(int32_t result);
// Callback for manual scheduling of paints when there is no flush callback
// pending.
void OnManualCallbackComplete(int32_t);
Instance* instance_;
// Non-owning pointer. See the constructor.
Client* client_;
bool is_always_opaque_;
CompletionCallbackFactory<PaintManager> callback_factory_;
// This graphics device will be is_null() if no graphics has been manually
// set yet.
Graphics2D graphics_;
PaintAggregator aggregator_;
// See comment for EnsureCallbackPending for more on how these work.
bool manual_callback_pending_;
bool flush_pending_;
// When we get a resize, we don't bind right away (see SetSize). The
// has_pending_resize_ tells us that we need to do a resize for the next
// paint operation. When true, the new size is in pending_size_.
bool has_pending_resize_;
Size pending_size_;
};
} // namespace pp
#endif // PPAPI_UTILITY_GRAPHICS_PAINT_MANAGER_H_