Move HiDPI-related Pepper interfaces to stable

ppapi/cpp/graphics_2d.h

 // 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_CPP_GRAPHICS_2D_H_
 #define PPAPI_CPP_GRAPHICS_2D_H_
 
 #include "ppapi/c/pp_stdint.h"
 #include "ppapi/cpp/resource.h"
 #include "ppapi/cpp/size.h"
@@ skipping 23 matching lines @@
   Graphics2D(const Graphics2D& other);
 
   /// A constructor allocating a new 2D graphics context with the given size
   /// in the browser, resulting object will be is_null() if the allocation
   /// failed.
   ///
   /// @param[in] instance The instance with which this resource will be
   /// associated.
   ///
   /// @param[in] size The size of the 2D graphics context in the browser,
   /// measured in device pixels.

[Josh Horwich, 2013/03/29 20:54:23]

I just noticed the use of "device pixels" here (and in size() docs) which is
actually incorrect, but not surprising seeing as this pre-dated HiDPI modes
(devicePixelRatio!=1) in Chrome.

It seems that the wording here should be a bit different, as a context without
SetScale applied will have these in DIPs (not device pixels) and one that has
SetScale applied will have them be "device pixels" only if the scale is actually
the inverse of the device scale (the recommended practice).

maybe just "measured in pixels." is technically accurate and covers all cases,
but might continue to confuse. What do you think?

[dmichael (off chromium), 2013/04/04 17:16:00]

Yes, that would probably be better. You might reference SetScale here for more
information.

[Josh Horwich, 2013/04/08 21:08:15]

Done.

   ///
   /// @param[in] is_always_opaque Set the <code>is_always_opaque</code> flag
   /// to true if you know that you will be painting only opaque data to this
   /// context. This option will disable blending when compositing the module
   /// with the web page, which might give higher performance on some computers.
   ///
   /// If you set <code>is_always_opaque</code>, your alpha channel should
   /// always be set to 0xFF or there may be painting artifacts. The alpha values
   /// overwrite the destination alpha values without blending when
   /// <code>is_always_opaque</code> is true.
@@ skipping 198 matching lines @@
   /// not issued its callback yet.  In the failure case, nothing will be
   /// updated and no callback will be scheduled.
 
   // TODO(darin): We should ensure that the completion callback always runs, so
   // that it is easier for consumers to manage memory referenced by a callback.
 
   // TODO(): Add back in the synchronous mode description once we have support
   // for it.
   int32_t Flush(const CompletionCallback& cc);
 
+  /// Returns true if SetScale and GetScale are supported. False if not.
+  static bool SupportsScale();

[dmichael (off chromium), 2013/03/28 21:38:29]

Hmm, I don't think we usually have this kind of function in the C++ wrappers. It
also seems like it would be unnecessary...  if we're running on a version of
Chrome that doesn't support these, then the View should give us a device scale
of 1.0, and a scale-aware plugin will just work as if it's on a device with
scale 1.0.

Is there a use case for this function I'm not thinking of?

[Josh Horwich, 2013/03/29 20:54:23]

I originally was worried about cases where view did give a scale, but for
whatever reason the graphics2d scale interface wasn't available (since
technically one could implement a Pepper host that supports view1_1 but
graphics2d_1_0), so a plugin could decide to revert to "DIPs only" if it knew
that SetScale wasn't actually available.

However, this is probably overkill in practice (and they could check SetScale's
result too I suppose) so I'll remove it.

+
+  /// SetScale() sets the scale factor that will be applied when painting the
+  /// graphics context onto the output device. Typically, if rendering at device
+  /// resolution is desired, the context would be created with the width and
+  /// height scaled up by the view's GetDeviceScale and SetScale called with a
+  /// scale of 1.0 / GetDeviceScale(). For example, if the view resource passed
+  /// to DidChangeView has a rectangle of (w=200, h=100) and a device scale of
+  /// 2.0, one would call Create with a size of (w=400, h=200) and then call
+  /// SetScale with 0.5. One would then treat each pixel in the context as a
+  /// single device pixel.
+  ///
+  /// @param[in] scale The scale to apply when painting.
+  ///
+  /// @return Returns <code>true</code> on success or <code>false</code>
+  /// if the resource is invalid or the scale factor is 0 or less.
+  bool SetScale(float scale);
+
+  /// GetScale() gets the scale factor that will be applied when painting the
+  /// graphics context onto the output device.
+  ///
+  /// @return Returns the scale factor for the graphics context. If the resource
+  /// is invalid, 0.0 will be returned.
+  float GetScale();

[dmichael (off chromium), 2013/03/28 21:38:29]

It would be good to mention somewhere that the default is always 1.0

[Josh Horwich, 2013/03/29 20:54:23]

Done.

+
  private:
   Size size_;
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_GRAPHICS_2D_H_