Unifying NativeMetafile class interface (as much as possible) for Linux, Mac, Win

printing/native_metafile.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 PRINTING_NATIVE_METAFILE_H_
 #define PRINTING_NATIVE_METAFILE_H_
 
 #include "base/basictypes.h"
-#include "build/build_config.h"

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

Still need this, no?

[dpapad, 2011/03/08 19:39:22]

Done.

 
 #if defined(OS_WIN)
-#include "printing/native_metafile_win.h"
+#include <windows.h>
+#include <vector>
 #elif defined(OS_MACOSX)
-#include "printing/native_metafile_mac.h"
-#elif defined(OS_POSIX)
-#include "printing/native_metafile_linux.h"
+#include <ApplicationServices/ApplicationServices.h>
+#include <CoreFoundation/CoreFoundation.h>
+#include "base/mac/scoped_cftyperef.h"
 #endif
 
+#if defined(OS_WIN)
+namespace gfx {
+class Rect;
+}
+#elif defined(OS_MACOSX)
+namespace gfx {

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

These can be done outside of a platform ifdef

[dpapad, 2011/03/08 19:39:22]

Done.

+class Rect;
+class Size;
+class Point;
+}
+#elif defined(OS_POSIX)
+typedef struct _cairo_surface cairo_surface_t;

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

cairo_surface_t isn't used here.  What does use it?

[dpapad, 2011/03/08 19:39:22]

Done.

+typedef struct _cairo cairo_t;

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

Looks like a per platform typedef might be useful...
PlatformContext:
linux -> _cairo
win -> HDC
mac -> CGContextRef

[dpapad, 2011/03/08 19:39:22]

Done.

+#endif
+
+class FilePath;
+
+namespace printing {
+
+// This class creates a graphics context that renders into a PDF data stream.

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

It doesn't always render to a PDF data stream.

[dpapad, 2011/03/08 19:39:22]

Done.

+class NativeMetafile {
+ public:
+  virtual ~NativeMetafile() {}
+
+  // Initializes a fresh new metafile for rendering. Returns false on failure.
+  // Note: It should only be called from within the renderer process to allocate
+  // rendering resources.
+  virtual bool Init() = 0;
+
+  // Initializes the metafile with the data in |src_buffer|. Returns true
+  // on success.
+  // Note: It should only be called from within the browser process.
+  virtual bool Init(const void* src_buffer, uint32 src_buffer_size) = 0;
+
+  // Returns the size of the underlying data stream. Only valid after Close()
+  // has been called.
+  virtual uint32 GetDataSize() const = 0;
+
+  // Copies the first |dst_buffer_size| bytes of the underlying data stream into
+  // |dst_buffer|. This function should ONLY be called after Close() is invoked.
+  // Returns true if the copy succeeds.
+  virtual bool GetData(void* dst_buffer, uint32 dst_buffer_size) const = 0;
+
+  // Closes the current page and destroys the context used in rendering that
+  // page. The results of current page will be appended into the underlying
+  // data stream. Returns true on success.
+  virtual bool FinishPage() = 0;
+
+  // Closes the metafile. No further rendering is allowed.

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

Maybe note that this implicitly finishes the current page?

[dpapad, 2011/03/08 19:39:22]

Done.

+  virtual void Close() = 0;
+
+  // Saves the underlying data to the given file. This function should ONLY be
+  // called after the metafile is closed. Returns true if writing succeeded.
+  virtual bool SaveTo(const FilePath& file_path) const = 0;

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

Is this only used by tests?  If so, we can make it protected and use friend
tests?

[dpapad, 2011/03/08 19:39:22]

No, it is used in non-test code (print_dialog_gtk.h:159).

+
+#if defined(OS_WIN)||defined(OS_MACOSX)
+  // Returns the bounds of the given page. Pages use a 1-based index.
+  virtual gfx::Rect GetPageBounds(unsigned int page_number) const = 0;

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

Lets make these not platform specific.

[dpapad, 2011/03/08 19:39:22]

Done.

+  virtual unsigned int GetPageCount() const = 0;
+#endif
+
+#if defined(OS_WIN)
+  // Generates a virtual HDC that will record every GDI commands and compile it
+  // in a EMF data stream.
+  // hdc is used to setup the default DPI and color settings. hdc is optional.
+  // rect specifies the dimensions (in .01-millimeter units) of the EMF. rect is
+  // optional.
+  virtual bool CreateDc(HDC sibling, const RECT* rect) = 0;

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

It'd be great to know if these methods are specific to the way we need to print
on windows, or if they are specific to EMF.  Maybe we'll only figure that out
when when we have a non EMF metafile implementation.

[dpapad, 2011/03/08 19:39:22]

These functions call internaly CreateEnhMetaFile(...). The description of that
method is (taken from the Windows dcoumentation)
"The CreateEnhMetaFile function creates a device context for an enhanced-format
metafile. This device context can be used to store a device-independent
picture."

I am not sure if they are useful for non-EMF related operations.

[vandebo (ex-Chrome), 2011/03/08 20:16:53]

That makes it sound like they are EMF specific.  Can you look at it more and see
if we can remove them from the nativemetafile interface and just have them in
the emf implementation?

[dpapad, 2011/03/08 22:17:19]

In several places (print_web_view_helper_win.cc, webplugin_delegate_stub.cc) the
following pattern is used

// other code
metafile->CreateDc(NULL, NULL);
HDC hdc = metafile->hdc();
skia::PlatformDevice::InitializeDC(hdc);
// other code that calls other NativeMetafile methods

Now calling CreateDc(NULL, NULL) looks like it is equivalent of calling
CreateEnhMetaFile(NULL,NULL,NULL.NULL) directly. Maybe substituting these two
calls can allow removing CreateDc from the interface. I would prefer to do this
on a separate CL.

+
+  // Similar to the above method but the metafile is backed by a file.
+  virtual bool CreateFileBackedDc(HDC sibling,
+                                  const RECT* rect,
+                                  const FilePath& path) = 0;
+
+  // TODO(maruel): CreateFromFile(). If ever used. Maybe users would like to

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

Is this ever used?

[dpapad, 2011/03/08 19:39:22]

No, it is not used anywhere. Should I remove it?

[vandebo (ex-Chrome), 2011/03/08 20:16:53]

Yea, we like to remove dead code.

[dpapad, 2011/03/08 22:17:19]

Done.

[dpapad, 2011/03/10 19:32:34]

It turns out that this function is called in
service_utility_process_host.cc:206, so I am going to restore it. 

+  // have the ability to save web pages to an EMF file? Afterward, it is easy to
+  // convert to PDF or PS.
+  // Load an EMF file.
+  virtual bool CreateFromFile(const FilePath& metafile_path) = 0;
+
+  // Closes the HDC created by CreateDc() and generates the compiled EMF
+  // data.
+  virtual bool CloseDc() = 0;
+
+  // "Plays" the EMF buffer in a HDC. It is the same effect as calling the
+  // original GDI function that were called when recording the EMF. |rect| is in
+  // "logical units" and is optional. If |rect| is NULL, the natural EMF bounds
+  // are used.
+  // Note: Windows has been known to have stack buffer overflow in its GDI
+  // functions, whether used directly or indirectly through precompiled EMF
+  // data. We have to accept the risk here. Since it is used only for printing,
+  // it requires user intervention.
+  virtual bool Playback(HDC hdc, const RECT* rect) const = 0;
+
+  // The slow version of Playback(). It enumerates all the records and play them
+  // back in the HDC. The trick is that it skip over the records known to have
+  // issue with some printers. See Emf::Record::SafePlayback implementation for
+  // details.
+  virtual bool SafePlayback(HDC hdc) const = 0;

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

Are both of the playback methods still used?

[dpapad, 2011/03/08 19:39:22]

They are both used (but only in emf_win_unittest.cc).

[vandebo (ex-Chrome), 2011/03/08 20:16:53]

If only used in emf unit tests, then they can be moved out of the nativemetafile
interface.

[dpapad, 2011/03/08 22:17:19]

Actually, it turns out that SafePlayback is not only called in unittests. It is
called in printed_document_win.cc and print_system_win.cc (under
chrome/service/cloud_print/).

+
+  // Retrieves the EMF stream. It is a helper function.
+  virtual bool GetData(std::vector<uint8>* buffer) const = 0;
+
+  // Inserts a custom GDICOMMENT records indicating StartPage/EndPage calls
+  // (since StartPage and EndPage do not work in a metafile DC). Only valid
+  // when hdc_ is non-NULL.
+  virtual bool StartPage() = 0;

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

For methods that are the same on the different platforms except for their
arguments etc., let's put them in their own ifdef block with just the one
method.

[dpapad, 2011/03/08 19:39:22]

Done.

+
+  virtual HENHMETAFILE emf() const = 0;
+  virtual HDC hdc() const = 0;
+#elif defined(OS_MACOSX)
+  // Prepares a new pdf page at specified |content_origin| with the given
+  // |page_size| and a |scale_factor| to use for the drawing.
+  virtual CGContextRef StartPage(const gfx::Size& page_size,
+                           const gfx::Point& content_origin,
+                           const float& scale_factor) = 0;
+
+  // Renders the given page into |rect| in the given context.
+  // Pages use a 1-based index. The rendering uses the following arguments
+  // to determine scaling and translation factors.
+  // |shrink_to_fit| specifies whether the output should be shrunk to fit the
+  // supplied |rect| if the page size is larger than |rect| in any dimension.
+  // If this is false, parts of the PDF page that lie outside the bounds will be
+  // clipped.
+  // |stretch_to_fit| specifies whether the output should be stretched to fit
+  // the supplied bounds if the page size is smaller than |rect| in all
+  // dimensions.
+  // |center_horizontally| specifies whether the final image (after any scaling
+  // is done) should be centered horizontally within the given |rect|.
+  // |center_vertically| specifies whether the final image (after any scaling
+  // is done) should be centered vertically within the given |rect|.
+  // Note that all scaling preserves the original aspect ratio of the page.
+  virtual bool RenderPage(unsigned int page_number,
+                          CGContextRef context,
+                          const CGRect rect,
+                          bool shrink_to_fit,
+                          bool stretch_to_fit,
+                          bool center_horizontally,
+                          bool center_vertically) const = 0;
+
+  // Get the context for rendering to the PDF.
+  virtual CGContextRef context() = 0;
+#elif defined(OS_POSIX)
+  // Sets raw PDF data for the document. This is used when a cairo drawing
+  // surface has already been created. This method will cause all subsequent
+  // drawing on the surface to be discarded (in Close()). If Init() has not yet
+  // been called this method simply calls the second version of Init.
+  virtual bool SetRawData(const void* src_buffer, uint32 src_buffer_size) = 0;
+
+  // Prepares a new cairo surface/context for rendering a new page.
+  // The unit is in point (=1/72 in).
+  // Returns NULL when failed.
+  virtual cairo_t* StartPage(double width_in_points,

[vandebo (ex-Chrome), 2011/03/08 00:39:35]

These arguments could be turned into two gfx::Size values.  Not sure if that
would get you close enough to the mac interface to unite them.

[dpapad, 2011/03/08 19:39:22]

gfx::Size stores width and height as integers. Here width and height are doubles
because that is what function cairo_pdf_surface_set_size(...), which is called
internally, expects. If there is no need for them to be doubles I could convert
them right before calling cairo_pdf_surface_set_size to ints, but I am not sure
that this is the case here.

[vandebo (ex-Chrome), 2011/03/08 20:16:53]

These are in points, it's ok to round these values by 1/72nd of an inch. i.e.
ints will work fine.

+                             double height_in_points,
+                             double margin_top_in_points,
+                             double margin_right_in_points,
+                             double margin_bottom_in_points,
+                             double margin_left_in_points) = 0;
+#endif
+};
+
+}  // namespace printing
+
 #endif  // PRINTING_NATIVE_METAFILE_H_