pdfviewer: more code comments + concat the pdf matrix with the existing matrix in canvas, instead o…

experimental/PdfViewer/SkPdfGraphicsState.h

 /*
  * Copyright 2013 Google Inc.
  *
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 #ifndef SkPdfGraphicsState_DEFINED
 #define SkPdfGraphicsState_DEFINED
 
 #include "SkCanvas.h"
 #include "SkPaint.h"
 #include "SkPdfConfig.h"
 #include "SkPdfUtils.h"
 
+class SkPdfAllocator;
 class SkPdfFont;
 class SkPdfDoc;
+class SkPdfNativeDoc;
 class SkPdfNativeObject;
 class SkPdfResourceDictionary;
 class SkPdfSoftMaskDictionary;
+#include "SkTypes.h"
 
-class SkPdfNativeDoc;
-class SkPdfAllocator;
 
-// TODO(edisonn): move this class in include/core?
-// Ref objects can't be dealt unless we use a specific class initialization
-// The difference between SkTDStackNew and SkTDStack is that SkTDStackNew uses new/delete
-// to be a manage c++ stuff (like initializations)
+// TODO(edisonn): move SkTDStackNester class in its own private file
 
 // Adobe limits it to 28, so 256 should be more than enough
 #define MAX_NESTING 256
 
-#include "SkTypes.h"
-template <typename T> class SkTDStackNew : SkNoncopyable {
+/** \class SkTDStackNester
+ *
+ * The difference between SkTDStackNester and SkTDStack is that:
+ *   - SkTDStackNester uses new/delete to manage initializations
+ *   - Supports nest/unnest which simulates a stack of stack. unnest will pop all the
+ *     objects pushed since the last nest
+ */
+
+template <typename T> class SkTDStackNester : SkNoncopyable {
 public:
-    SkTDStackNew() : fCount(0), fTotalCount(0), fLocalCount(0) {
+    SkTDStackNester() : fCount(0), fTotalCount(0), fLocalCount(0) {
         fInitialRec.fNext = NULL;
         fRec = &fInitialRec;
 
     //  fCount = kSlotCount;
     }
 
-    ~SkTDStackNew() {
+    ~SkTDStackNester() {
         Rec* rec = fRec;
         while (rec != &fInitialRec) {
             Rec* next = rec->fNext;
             delete rec;
             rec = next;
         }
     }
 
     int count() const { return fLocalCount; }
     int depth() const { return fLocalCount; }
@@ skipping 96 matching lines @@
         Rec* fNext;
         T    fSlots[kSlotCount];
     };
     Rec     fInitialRec;
     Rec*    fRec;
     int     fCount, fTotalCount, fLocalCount;
     int     fNestings[MAX_NESTING];
     int     fNestingLevel;
 };
 
-// TODO(edisonn): better class design.
+/** \class SkTDStackNester
+ *   Operates on stroking or non-stroking properties.
+ */
 class SkPdfColorOperator {
 
     /*
     color space   name or array     The current color space in which color values are to be interpreted
                                     (see Section 4.5, “Color Spaces”). There are two separate color space
                                     parameters: one for stroking and one for all other painting opera-
                                     tions. Initial value: DeviceGray.
      */
 
     // TODO(edisonn): implement the array part too
-    // does not own the char*
 // TODO(edisonn): remove this public, let fields be private
-// TODO(edisonn): make color space an enum!
 public:
     NotOwnedString fColorSpace;
     SkPdfNativeObject* fPattern;
 
     /*
     color         (various)         The current color to be used during painting operations (see Section
                                     4.5, “Color Spaces”). The type and interpretation of this parameter
                                     depend on the current color space; for most color spaces, a color
                                     value consists of one to four numbers. There are two separate color
                                     parameters: one for stroking and one for all other painting opera-
                                     tions. Initial value: black.
      */
 
     SkColor fColor;
     double fOpacity;  // ca or CA
 
-    // TODO(edisonn): add here other color space options.
-
 public:
     void setRGBColor(SkColor color) {
         // TODO(edisonn): ASSERT DeviceRGB is the color space.
         fPattern = NULL;
         fColor = color;
     }
-    // TODO(edisonn): double check the default values for all fields.
+
+    // TODO(edisonn): implement the default values for all fields.
     SkPdfColorOperator() : fPattern(NULL), fColor(SK_ColorBLACK), fOpacity(1) {
         NotOwnedString::init(&fColorSpace, "DeviceRGB");
     }
 
     void setColorSpace(NotOwnedString* colorSpace) {
         fColorSpace = *colorSpace;
         fPattern = NULL;
     }
 
     void setPatternColorSpace(SkPdfNativeObject* pattern) {
         fColorSpace.fBuffer = (const unsigned char*)"Pattern";
         fColorSpace.fBytes = 7;  // strlen("Pattern")
         fPattern = pattern;
     }
 
     void applyGraphicsState(SkPaint* paint) {
         paint->setColor(SkColorSetA(fColor, (U8CPU)(fOpacity * 255)));
     }
 };
 
-// TODO(edisonn): better class design.
+/** \class SkTDStackNester
+ *   Operates on stroking or non-stroking properties.
+ */
 struct SkPdfGraphicsState {
     // TODO(edisonn): deprecate and remove these!
     double              fCurPosX;
     double              fCurPosY;
 
     double              fCurFontSize;
     bool                fTextBlock;
     SkPdfFont*          fSkFont;
     SkPath              fPath;
     bool                fPathClosed;
 
     double              fTextLeading;
     double              fWordSpace;
     double              fCharSpace;
 
     SkPdfResourceDictionary* fResources;
 
 
-    // TODO(edisonn): move most of these in canvas/paint?
-    // we could have some in canvas (matrixes?),
-    // some in 2 paints (stroking paint and non stroking paint)
+    // TODO(edisonn): Can we move most of these in canvas/paint?
+    // Might need to strore some properties in 2 paints (stroking paint and non stroking paint)
 
 //    TABLE 4.2 Device-independent graphics state parameters
 /*
  * CTM           array             The current transformation matrix, which maps positions from user
                                 coordinates to device coordinates (see Section 4.2, “Coordinate Sys-
                                 tems”). This matrix is modified by each application of the coordi-
                                 nate transformation operator, cm. Initial value: a matrix that
                                 transforms default user coordinates to device coordinates.
  */
     SkMatrix fCTM;
@@ skipping 199 matching lines @@
 /*
 smoothness             number             (PDF 1.3) The precision with which color gradients are to be ren-
                                           dered on the output device (see Section 6.5.2, “Smoothness Toler-
                                           ance”). The value of this parameter gives the maximum error
                                           tolerance, expressed as a fraction of the range of each color compo-
                                           nent; smaller numbers give smoother color transitions at the
                                           expense of more computation and memory use. Initial value:
                                           installation-dependent.
  */
 
-
-
     // TODO(edisonn): some defaults are contextual, they could on colorspace, pdf version, ...
-
     SkPdfGraphicsState() {
         fCurPosX      = 0.0;
         fCurPosY      = 0.0;
         fCurFontSize  = 0.0;
         fTextBlock    = false;
         fCTM          = SkMatrix::I();
         fMatrixTm     = SkMatrix::I();
         fMatrixTlm    = SkMatrix::I();
         fPathClosed   = true;
         fLineWidth    = 0;
@@ skipping 12 matching lines @@
         fDashPhase    = 0;
         fBlendModesLength = 1;
         fBlendModes[0] = SkXfermode::kSrc_Mode;  // PDF: Normal Blend mode
         fSMask        = NULL;
     }
 
     // TODO(edisonn): make two functions instead, stroking and non stoking, avoid branching
     void applyGraphicsState(SkPaint* paint, bool stroking);
 };
 
+/** \class SkPdfContext
+ *   The context of the drawing. The document we draw from, the current stack of objects, ...
+ */
 class SkPdfContext {
 public:
-    SkTDStackNew<SkPdfNativeObject*>  fObjectStack;
-    SkTDStackNew<SkPdfGraphicsState>  fStateStack;
+    SkTDStackNester<SkPdfNativeObject*>  fObjectStack;
+    SkTDStackNester<SkPdfGraphicsState>  fStateStack;
     SkPdfGraphicsState              fGraphicsState;
     SkPdfNativeDoc*                 fPdfDoc;
-    // TODO(edisonn): the allocator, could be freed after the page is done drawing, so we have the
-    // pixels on the screen asap.
     SkPdfAllocator*                 fTmpPageAllocator;
     SkMatrix                        fOriginalMatrix;
 
     SkPdfContext(SkPdfNativeDoc* doc);
     ~SkPdfContext();
 };
 
 #endif  // SkPdfGraphicsState_DEFINED