Move QPDFMatrix into the public API

Jay Berkenbilt
1 parent 07f40bd2
Showing 4 changed files with 57 additions and 5 deletions
ChangeLog
libqpdf/qpdf/QPDFMatrix.hh → include/qpdf/QPDFMatrix.hh
libqpdf/QPDFMatrix.cc
manual/qpdf-manual.xml
 2021-02-12  Jay Berkenbilt  <ejb@ql.org>
+	* Move formerly internal QPDFMatrix class to the public API. This
+	class provides convenience methods for working with transformation
+	matrices.
+
 	* QUtil::double_to_string: trim trailing zeroes by default, and
 	add option to not trim trailing zeroes. This causes a syntactic
 	but semantically preserving change in output when doubles are
+// Copyright (c) 2005-2021 Jay Berkenbilt
+//
+// This file is part of qpdf.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Versions of qpdf prior to version 7 were released under the terms
+// of version 2.0 of the Artistic License. At your option, you may
+// continue to consider qpdf to be licensed under those terms. Please
+// see the manual for additional information.
+
 #ifndef QPDFMATRIX_HH
 #define QPDFMATRIX_HH
@@ -5,6 +26,15 @@
 #include <qpdf/DLL.h>
 #include <string>
+// This class represents a PDF transformation matrix using a tuple
+// such that
+//
+//                      ┌       ┐
+//                      │ a b 0 │
+// (a, b, c, d, e, f) = │ c d 0 │
+//                      │ e f 1 │
+//                      └       ┘
+
 class QPDFMatrix
 {
   public:
@@ -16,27 +46,39 @@ class QPDFMatrix
     QPDF_DLL
     QPDFMatrix(QPDFObjectHandle::Matrix const&);
+    // Returns the six values separated by spaces as real numbers with
+    // trimmed zeroes.
     QPDF_DLL
     std::string unparse() const;
     QPDF_DLL
     QPDFObjectHandle::Matrix getAsMatrix() const;
-    // This is not part of the public API. Just provide the methods we
-    // need as we need them.
+    // Replace this with other * this
     QPDF_DLL
     void concat(QPDFMatrix const& other);
+
+    // Same as concat(sx, 0, 0, sy, 0, 0)
     QPDF_DLL
     void scale(double sx, double sy);
+
+    // Same as concat(1, 0, 0, 1, tx, ty);
     QPDF_DLL
     void translate(double tx, double ty);
+
     // Any value other than 90, 180, or 270 is ignored
     QPDF_DLL
     void rotatex90(int angle);
+    // Transform a point. The underlying operation is to take
+    // [x y 1] * this
+    // and take the first and second rows of the result as xp and yp.
     QPDF_DLL
     void transform(double x, double y, double& xp, double& yp);
+    // Transform a rectangle by creating a new rectangle that tightly
+    // bounds the polygon resulting from transforming the four
+    // corners.
     QPDF_DLL
     QPDFObjectHandle::Rectangle transformRectangle(
         QPDFObjectHandle::Rectangle r);
@@ -118,9 +118,6 @@ QPDFMatrix::transform(double x, double y, double&amp; xp, double&amp; yp)
 QPDFObjectHandle::Rectangle
 QPDFMatrix::transformRectangle(QPDFObjectHandle::Rectangle r)
 {
-    // Transform a rectangle by creating a new rectangle the tightly
-    // bounds the polygon resulting from transforming the four
-    // corners.
     std::vector<double> tx(4);
     std::vector<double> ty(4);
     transform(r.llx, r.lly, tx.at(0), ty.at(0));
@@ -5220,6 +5220,15 @@ print &quot;\n&quot;;
           rotations.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          The <classname>QPDFMatrix</classname> class, formerly a
+          private, internal class, has been added to the public API.
+          See <filename>include/qpdf/QPDFMatrix.hh</filename> for
+          details. This class is for working with transformation
+          matrices.
+         </para>
+        </listitem>
        </itemizedlist>
       </listitem>
       <listitem>