Clarify GraphicsContext::beginLayer()/endLayer() have unexpected behaviors.

Source/platform/graphics/GraphicsContext.h

 /*
  * Copyright (C) 2003, 2006, 2007, 2008, 2009 Apple Inc. All rights reserved.
  * Copyright (C) 2008-2009 Torch Mobile, Inc.
  * Copyright (C) 2013 Google Inc. All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
  * are met:
  * 1. Redistributions of source code must retain the above copyright
  *    notice, this list of conditions and the following disclaimer.
@@ skipping 91 matching lines @@
     bool contextDisabled() const { return m_disabledState; }
 
     // ---------- State management methods -----------------
     void save();
     void restore();
     unsigned saveCount() { return m_canvasStateStack.size(); }
 #if ENABLE(ASSERT)
     void disableDestructionChecks() { m_disableDestructionChecks = true; }
 #endif
 
-    void saveLayer(const SkRect* bounds, const SkPaint*);
-    void restoreLayer();
-
     bool hasStroke() const { return strokeStyle() != NoStroke && strokeThickness() > 0; }
 
     float strokeThickness() const { return immutableState()->strokeData().thickness(); }
     void setStrokeThickness(float thickness) { mutableState()->setStrokeThickness(thickness); }
 
     StrokeStyle strokeStyle() const { return immutableState()->strokeData().style(); }
     void setStrokeStyle(StrokeStyle style) { mutableState()->setStrokeStyle(style); }
 
     Color strokeColor() const { return immutableState()->strokeColor(); }
     void setStrokeColor(const Color& color) { mutableState()->setStrokeColor(color); }
@@ skipping 204 matching lines @@
     void drawBidiText(const Font&, const TextRunPaintInfo&, const FloatPoint&, Font::CustomFontNotReadyAction = Font::DoNotPaintIfFontNotReady);
     void drawHighlightForText(const Font&, const TextRun&, const FloatPoint&, int h, const Color& backgroundColor, int from = 0, int to = -1);
 
     void drawLineForText(const FloatPoint&, float width, bool printing);
     enum DocumentMarkerLineStyle {
         DocumentMarkerSpellingLineStyle,
         DocumentMarkerGrammarLineStyle
     };
     void drawLineForDocumentMarker(const FloatPoint&, float width, DocumentMarkerLineStyle);
 
+    // This behaves the same as save(), but in addition it allocates an offscreen buffer.
     void beginTransparencyLayer(float opacity, const FloatRect* = 0);
+    // Apply CompositeOperator when the layer is composited on the backdrop (i.e. endLayer()).
+    // Don't change the current CompositeOperator state.
     void beginLayer(float opacity, CompositeOperator, const FloatRect* = 0, ColorFilter = ColorFilterNone, ImageFilter* = 0);
     void endLayer();
 
     void beginCull(const FloatRect&);
     void endCull();
 
     // Instead of being dispatched to the active canvas, draw commands following beginRecording()
     // are stored in a display list that can be replayed at a later time. Pass in the bounding
     // rectangle for the content in the list.
     void beginRecording(const FloatRect&, uint32_t = 0);
@@ skipping 90 matching lines @@
 #else
     static inline int focusRingOutset(int offset) { return 0; }
     static inline int focusRingWidth(int width) { return 1; }
     static SkPMColor lineColors(int);
     static SkPMColor antiColors1(int);
     static SkPMColor antiColors2(int);
     static void draw1xMarker(SkBitmap*, int);
     static void draw2xMarker(SkBitmap*, int);
 #endif
 
+    void saveLayer(const SkRect* bounds, const SkPaint*);
+    void restoreLayer();
+
     // Helpers for drawing a focus ring (drawFocusRing)
     float prepareFocusRingPaint(SkPaint&, const Color&, int width) const;
     void drawFocusRingPath(const SkPath&, const Color&, int width);
     void drawFocusRingRect(const SkRect&, const Color&, int width);
 
     // SkCanvas wrappers.
     void clipPath(const SkPath&, AntiAliasingMode = NotAntiAliased, SkRegion::Op = SkRegion::kIntersect_Op);
     void clipRRect(const SkRRect&, AntiAliasingMode = NotAntiAliased, SkRegion::Op = SkRegion::kIntersect_Op);
     void concat(const SkMatrix&);
     void drawRRect(const SkRRect&, const SkPaint&);
@@ skipping 81 matching lines @@
     bool m_accelerated : 1;
     bool m_isCertainlyOpaque : 1;
     bool m_printing : 1;
     bool m_antialiasHairlineImages : 1;
     bool m_shouldSmoothFonts : 1;
 };
 
 } // namespace blink
 
 #endif // GraphicsContext_h