Simplify platform_canvas.h by recognizing that PlatformCanvas does not actually extend

skia/ext/platform_canvas.h

 // Copyright (c) 2011 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 SKIA_EXT_PLATFORM_CANVAS_H_
 #define SKIA_EXT_PLATFORM_CANVAS_H_
 
 // The platform-specific device will include the necessary platform headers
 // to get the surface type.
 #include "base/basictypes.h"
 #include "skia/ext/platform_device.h"
 #include "third_party/skia/include/core/SkCanvas.h"
 
 namespace skia {
 
-// This class is a specialization of the regular SkCanvas that is designed to
-// work with a PlatformDevice to manage platform-specific drawing. It allows
-// using both Skia operations and platform-specific operations.
-class SK_API PlatformCanvas : public SkCanvas {
- public:
-  // If you use the version with no arguments, you MUST call initialize()
-  PlatformCanvas();
-  // Set is_opaque if you are going to erase the bitmap and not use
-  // transparency: this will enable some optimizations.
-  PlatformCanvas(int width, int height, bool is_opaque);
+typedef SkCanvas PlatformCanvas;
+
+/*

[brettw, 2012/11/12 21:08:52]

Can you use //-style comments instead? We only do it your way in .c files.

[reed1, 2012/11/14 14:01:43]

Done.

+ *  Note about error handling.
+ *
+ *  Creating a canvas can fail at times, most often because we fail to allocate
+ *  the backing-store (pixels). This can be from out-of-memory, or something
+ *  more opaque, like GDI or cairo reported a failure.
+ *
+ *  To allow the caller to handle the failure, every Create... factory takes an
+ *  enum as its last parameter. The default value is kCrashOnFailure. If the
+ *  caller passes kReturnNullOnFailure, then the caller is responsible to check
+ *  the return result.
+ */
+enum OnFailureType {
+  CRASH_ON_FAILURE,
+  RETURN_NULL_ON_FAILURE
+};
 
 #if defined(WIN32)
   // The shared_section parameter is passed to gfx::PlatformDevice::create.
   // See it for details.
-  PlatformCanvas(int width, int height, bool is_opaque, HANDLE shared_section);
+  SK_API SkCanvas* CreatePlatformCanvas(int width,
+                                        int height,
+                                        bool is_opaque,
+                                        HANDLE shared_section,
+                                        OnFailureType failure_type);
 #elif defined(__APPLE__)
-  PlatformCanvas(int width, int height, bool is_opaque,
-                 CGContextRef context);
-  PlatformCanvas(int width, int height, bool is_opaque, uint8_t* context);
+  SK_API SkCanvas* CreatePlatformCanvas(CGContextRef context,
+                                        int width,
+                                        int height,
+                                        bool is_opaque,
+                                        OnFailureType failure_type);
+
+  SK_API SkCanvas* CreatePlatformCanvas(int width,
+                                        int height,
+                                        bool is_opaque,
+                                        uint8_t* context,
+                                        OnFailureType failure_type);
 #elif defined(__linux__) || defined(__FreeBSD__) || defined(__OpenBSD__) || \
       defined(__sun) || defined(ANDROID)
   // Linux ---------------------------------------------------------------------
 
   // Construct a canvas from the given memory region. The memory is not cleared
   // first. @data must be, at least, @height * StrideForWidth(@width) bytes.
-  PlatformCanvas(int width, int height, bool is_opaque, uint8_t* data);
+  SK_API SkCanvas* CreatePlatformCanvas(int width,
+                                        int height,
+                                        bool is_opaque,
+                                        uint8_t* data,
+                                        OnFailureType failure_type);
 #endif
 
-  virtual ~PlatformCanvas();
+static inline SkCanvas* CreatePlatformCanvas(int width,
+                                             int height,
+                                             bool is_opaque) {
+  return CreatePlatformCanvas(width, height, is_opaque, 0, CRASH_ON_FAILURE);
+}
 
-#if defined(WIN32)
-  // For two-part init, call if you use the no-argument constructor above. Note
-  // that we want this to optionally match the Linux initialize if you only
-  // pass 3 arguments, hence the evil default argument.
-  bool initialize(int width, int height, bool is_opaque,
-                  HANDLE shared_section = NULL);
-#elif defined(__APPLE__)
-  // For two-part init, call if you use the no-argument constructor above
-  bool initialize(CGContextRef context, int width, int height, bool is_opaque);
-  bool initialize(int width, int height, bool is_opaque, uint8_t* data = NULL);
+// Takes ownership of the device, so the caller need not call unref().
+SK_API SkCanvas* CreateCanvas(SkDevice* device, OnFailureType failure_type);
 
-#elif defined(__linux__) || defined(__FreeBSD__) || defined(__OpenBSD__) || \
-      defined(__sun) || defined(ANDROID)
-  // For two-part init, call if you use the no-argument constructor above
-  bool initialize(int width, int height, bool is_opaque, uint8_t* data = NULL);
-#endif
+static inline SkCanvas* CreateBitmapCanvas(int width,
+                                           int height,
+                                           bool is_opaque) {
+  return CreatePlatformCanvas(width, height, is_opaque, 0, CRASH_ON_FAILURE);
+}
 
-  // Shared --------------------------------------------------------------------
+static inline SkCanvas* TryCreateBitmapCanvas(int width,
+                                              int height,
+                                              bool is_opaque) {
+  return CreatePlatformCanvas(width, height, is_opaque, 0,
+                              RETURN_NULL_ON_FAILURE);
+}
 
-  // Return the stride (length of a line in bytes) for the given width. Because
-  // we use 32-bits per pixel, this will be roughly 4*width. However, for
-  // alignment reasons we may wish to increase that.
-  static size_t StrideForWidth(unsigned width);
+class SK_API ScopedPlatformCanvas : public SkAutoTUnref<SkCanvas> {
+ public:
+  ScopedPlatformCanvas(int width, int height, bool is_opaque)
+      : SkAutoTUnref<SkCanvas>(CreatePlatformCanvas(width, height, is_opaque)){}
+};
 
-  // Allow callers to see the non-virtual function even though we have an
-  // override of a virtual one.
-  // FIXME(brettw) is this necessary?
-  using SkCanvas::clipRect;
-
- private:
-  // Helper method used internally by the initialize() methods.
-  bool initializeWithDevice(SkDevice* device);
-
-  // Disallow copy and assign
-  PlatformCanvas(const PlatformCanvas&);
-  PlatformCanvas& operator=(const PlatformCanvas&);
-};
+// Return the stride (length of a line in bytes) for the given width. Because
+// we use 32-bits per pixel, this will be roughly 4*width. However, for
+// alignment reasons we may wish to increase that.
+SK_API size_t PlatformCanvasStrideForWidth(unsigned width);
 
 // Returns the SkDevice pointer of the topmost rect with a non-empty
 // clip. In practice, this is usually either the top layer or nothing, since
 // we usually set the clip to new layers when we make them.
 //
 // If there is no layer that is not all clipped out, this will return a
 // dummy device so callers do not have to check. If you are concerned about
 // performance, check the clip before doing any painting.
 //
 // This is different than SkCanvas' getDevice, because that returns the
 // bottommost device.
 //
 // Danger: the resulting device should not be saved. It will be invalidated
 // by the next call to save() or restore().
 SK_API SkDevice* GetTopDevice(const SkCanvas& canvas);
 
-// Creates a canvas with raster bitmap backing.
-// Set is_opaque if you are going to erase the bitmap and not use
-// transparency: this will enable some optimizations.
-SK_API SkCanvas* CreateBitmapCanvas(int width, int height, bool is_opaque);
-
-// Non-crashing version of CreateBitmapCanvas
-// returns NULL if allocation fails for any reason.
-// Use this instead of CreateBitmapCanvas in places that are likely to
-// attempt to allocate very large canvases (therefore likely to fail),
-// and where it is possible to recover gracefully from the failed allocation.
-SK_API SkCanvas* TryCreateBitmapCanvas(int width, int height, bool is_opaque);
-
 // Returns true if native platform routines can be used to draw on the
 // given canvas. If this function returns false, BeginPlatformPaint will
 // return NULL PlatformSurface.
 SK_API bool SupportsPlatformPaint(const SkCanvas* canvas);
 
 // Draws into the a native platform surface, |context|.  Forwards to
 // DrawToNativeContext on a PlatformDevice instance bound to the top device.
 // If no PlatformDevice instance is bound, is a no-operation.
-SK_API void DrawToNativeContext(SkCanvas* canvas, PlatformSurface context,
-                                int x, int y, const PlatformRect* src_rect);
+SK_API void DrawToNativeContext(SkCanvas* canvas,
+                                PlatformSurface context,
+                                int x,
+                                int y,
+                                const PlatformRect* src_rect);
 
 // Sets the opacity of each pixel in the specified region to be opaque.
 SK_API void MakeOpaque(SkCanvas* canvas, int x, int y, int width, int height);
 
 // These calls should surround calls to platform drawing routines, the
 // surface returned here can be used with the native platform routines.
 //
 // Call EndPlatformPaint when you are done and want to use skia operations
 // after calling the platform-specific BeginPlatformPaint; this will
 // synchronize the bitmap to OS if necessary.
@@ skipping 40 matching lines @@
   SkBitmap bitmap_;
   PlatformSurface surface_; // initialized to 0
   intptr_t platform_extra_; // initialized to 0, specific to each platform
 
   DISALLOW_COPY_AND_ASSIGN(PlatformBitmap);
 };
 
 }  // namespace skia
 
 #endif  // SKIA_EXT_PLATFORM_CANVAS_H_