Convert pages to form XObjects

Support conversion of pages to form XObjects and placement of form
XObjects on pages.

1 files changed, 63 insertions, 0 deletions

diff --git a/include/qpdf/QPDFPageObjectHelper.hh b/include/qpdf/QPDFPageObjectHelper.hh
index eb72f7aa..0cd6be32 100644
--- a/include/qpdf/QPDFPageObjectHelper.hh
+++ b/include/qpdf/QPDFPageObjectHelper.hh
@@ -51,6 +51,21 @@ class QPDFPageObjectHelper: public QPDFObjectHelper
     QPDFObjectHandle
     getAttribute(std::string const& name, bool copy_if_shared);
 
+    // Return the TrimBox. If not defined, fall back to CropBox
+    QPDF_DLL
+    QPDFObjectHandle
+    getTrimBox(bool copy_if_shared = false);
+
+    // Return the CropBox. If not defined, fall back to MediaBox
+    QPDF_DLL
+    QPDFObjectHandle
+    getCropBox(bool copy_if_shared = false);
+
+    // Return the MediaBox
+    QPDF_DLL
+    QPDFObjectHandle
+    getMediaBox(bool copy_if_shared = false);
+
     // Returns an empty map if there are no images or no resources.
     // Prior to qpdf 8.4.0, this function did not support inherited
     // resources, but it does now. Return value is a map from XObject
@@ -162,6 +177,54 @@ class QPDFPageObjectHelper: public QPDFObjectHelper
     QPDF_DLL
     QPDFPageObjectHelper shallowCopyPage();
 
+    // Return a transformation matrix whose effect is the same as the
+    // page's /Rotate and /UserUnit parameters. If invert is true,
+    // return a matrix whose effect is the opposite. The regular
+    // matrix is suitable for taking something from this page to put
+    // elsewhere, and the second one is suitable for putting something
+    // else onto this page. The page's TrimBox is used as the bounding
+    // box for purposes of computing the matrix.
+    QPDF_DLL
+    QPDFObjectHandle::Matrix getMatrixForTransformations(bool invert = false);
+
+    // Return a form XObject that draws this page. This is useful for
+    // n-up operations, underlay, overlay, thumbnail generation, or
+    // any other case in which it is useful to replicate the contents
+    // of a page in some other context. The dictionaries are shallow
+    // copies of the original page dictionary, and the contents are
+    // coalesced from the page's contents. The resulting object handle
+    // is not referenced anywhere. If handle_transformations is true,
+    // the resulting form XObject's /Matrix will be set to replicate
+    // rotation (/Rotate) and scaling (/UserUnit) in the page's
+    // dictionary. In this way, the page's transformations will be
+    // preserved when placing this object on another page.
+    QPDF_DLL
+    QPDFObjectHandle getFormXObjectForPage(bool handle_transformations = true);
+
+    // Return content stream text that will place the given form
+    // XObject (fo) using the resource name "name" on this page
+    // centered within the given rectangle and shrunk to fit if
+    // necessary. If invert_transformations is true, the effect of any
+    // rotation (/Rotate) and scaling (/UserUnit) applied to the
+    // current page will be inverted in the form XObject placement.
+    // This will cause the form XObject's absolute orientation to be
+    // preserved. You could overlay one page on another by calling
+    // getFormXObjectForPage on the original page,
+    // QPDFObjectHandle::getUniqueResourceName on the destination
+    // page's Resources dictionary to generate a name for the
+    // resulting object, and calling placeFormXObject on the
+    // destination page. Then insert the new fo (or, if it comes from
+    // a different file, the result of calling copyForeignObject on
+    // it) into the resources dictionary using name, and append or
+    // prepend the content to the page's content streams. See the
+    // overlay/underlay code in qpdf.cc or
+    // examples/pdf-overlay-page.cc for an example.
+    QPDF_DLL
+    std::string placeFormXObject(
+        QPDFObjectHandle fo, std::string name,
+        QPDFObjectHandle::Rectangle rect,
+        bool invert_transformations = true);
+
   private:
     class Members
     {