third_party/WebKit/Source/platform/graphics/paint/DisplayItem.h

// Copyright 2014 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 DisplayItem_h
#define DisplayItem_h

#include "platform/PlatformExport.h"
#include "platform/graphics/ContiguousContainer.h"
#include "platform/graphics/paint/DisplayItemClient.h"
#include "wtf/Allocator.h"
#include "wtf/Assertions.h"
#include "wtf/Noncopyable.h"

#ifndef NDEBUG
#include "wtf/text/StringBuilder.h"
#include "wtf/text/WTFString.h"
#endif

class SkPictureGpuAnalyzer;

namespace blink {

class GraphicsContext;
class IntRect;
class WebDisplayItemList;

class PLATFORM_EXPORT DisplayItem {
    DISALLOW_NEW_EXCEPT_PLACEMENT_NEW();
public:
    enum {
        // Must be kept in sync with core/paint/PaintPhase.h.
        kPaintPhaseMax = 11,
    };

    // A display item type uniquely identifies a display item of a client.
    // Some display item types can be categorized using the following directives:
    // - In enum Type:
    //   - enum value <Category>First;
    //   - enum values of the category, first of which should equal <Category>First;
    //     (for ease of maintenance, the values should be in alphabetic order)
    //   - enum value <Category>Last which should be equal to the last of the enum values of the category
    // - DEFINE_CATEGORY_METHODS(<Category>) to define is<Category>Type(Type) and is<Category>() methods.
    //
    // A category or subset of a category can contain types each of which corresponds to a PaintPhase:
    // - In enum Type:
    //   - enum value <Category>[<Subset>]PaintPhaseFirst;
    //   - enum value <Category>[<Subset>]PaintPhaseLast = <Category>[<Subset>]PaintPhaseFirst + PaintPhaseMax;
    // - DEFINE_PAINT_PHASE_CONVERSION_METHOD(<Category>[<Subset>]) to define
    //   paintPhaseTo<Category>[<Subset>]Type(PaintPhase) method.
    //
    // A category can be derived from another category, containing types each of which corresponds to a
    // value of the latter category:
    // - In enum Type:
    //   - enum value <Category>First;
    //   - enum value <Category>Last = <Category>First + <BaseCategory>Last - <BaseCategory>First;
    // - DEFINE_CONVERSION_METHODS(<Category>, <category>, <BaseCategory>, <baseCategory>) to define methods to
    //   convert types between the categories;
    enum Type {
        kDrawingFirst,
        kDrawingPaintPhaseFirst = kDrawingFirst,
        kDrawingPaintPhaseLast = kDrawingFirst + kPaintPhaseMax,
        kBoxDecorationBackground,
        kCaret,
        kColumnRules,
        kDebugDrawing,
        kDocumentBackground,
        kDragImage,
        kDragCaret,
        kSVGImage,
        kLinkHighlight,
        kImageAreaFocusRing,
        kPageOverlay,
        kPageWidgetDelegateBackgroundFallback,
        kPopupContainerBorder,
        kPopupListBoxBackground,
        kPopupListBoxRow,
        kPrintedContentBackground,
        kPrintedContentDestinationLocations,
        kPrintedContentLineBoundary,
        kPrintedContentPDFURLRect,
        kResizer,
        kSVGClip,
        kSVGFilter,
        kSVGMask,
        kScrollbarBackButtonEnd,
        kScrollbarBackButtonStart,
        kScrollbarBackground,
        kScrollbarBackTrack,
        kScrollbarCorner,
        kScrollbarForwardButtonEnd,
        kScrollbarForwardButtonStart,
        kScrollbarForwardTrack,
        kScrollbarThumb,
        kScrollbarTickmarks,
        kScrollbarTrackBackground,
        kScrollbarCompositedScrollbar,
        kSelectionTint,
        kTableCellBackgroundFromColumnGroup,
        kTableCellBackgroundFromColumn,
        kTableCellBackgroundFromSection,
        kTableCellBackgroundFromRow,
        // Table collapsed borders can be painted together (e.g., left & top) but there are at most 4 phases of collapsed
        // border painting for a single cell. To disambiguate these phases of collapsed border painting, a mask is used.
        // TableCollapsedBorderBase can be larger than TableCollapsedBorderUnalignedBase to ensure the base lower bits are 0's.
        kTableCollapsedBorderUnalignedBase,
        kTableCollapsedBorderBase = (((kTableCollapsedBorderUnalignedBase - 1) >> 4) + 1) << 4,
        kTableCollapsedBorderLast = kTableCollapsedBorderBase + 0x0f,
        kTableSectionBoxShadowInset,
        kTableSectionBoxShadowNormal,
        kTableRowBoxShadowInset,
        kTableRowBoxShadowNormal,
        kVideoBitmap,
        kWebPlugin,
        kWebFont,
        kReflectionMask,
        kDrawingLast = kReflectionMask,

        kForeignLayerFirst,
        kForeignLayerCanvas = kForeignLayerFirst,
        kForeignLayerPlugin,
        kForeignLayerVideo,
        kForeignLayerLast = kForeignLayerVideo,

        kClipFirst,
        kClipBoxPaintPhaseFirst = kClipFirst,
        kClipBoxPaintPhaseLast = kClipBoxPaintPhaseFirst + kPaintPhaseMax,
        kClipColumnBoundsPaintPhaseFirst,
        kClipColumnBoundsPaintPhaseLast = kClipColumnBoundsPaintPhaseFirst + kPaintPhaseMax,
        kClipLayerFragmentPaintPhaseFirst,
        kClipLayerFragmentPaintPhaseLast = kClipLayerFragmentPaintPhaseFirst + kPaintPhaseMax,
        kClipFileUploadControlRect,
        kClipFrameToVisibleContentRect,
        kClipFrameScrollbars,
        kClipLayerBackground,
        kClipLayerColumnBounds,
        kClipLayerFilter,
        kClipLayerForeground,
        kClipLayerParent,
        kClipLayerOverflowControls,
        kClipNodeImage,
        kClipPopupListBoxFrame,
        kClipScrollbarsToBoxBounds,
        kClipSelectionImage,
        kPageWidgetDelegateClip,
        kClipPrintedPage,
        kClipLast = kClipPrintedPage,

        kEndClipFirst,
        kEndClipLast = kEndClipFirst + kClipLast - kClipFirst,

        kFloatClipFirst,
        kFloatClipPaintPhaseFirst = kFloatClipFirst,
        kFloatClipPaintPhaseLast = kFloatClipFirst + kPaintPhaseMax,
        kFloatClipLast = kFloatClipPaintPhaseLast,
        kEndFloatClipFirst,
        kEndFloatClipLast = kEndFloatClipFirst + kFloatClipLast - kFloatClipFirst,

        kScrollFirst,
        kScrollPaintPhaseFirst = kScrollFirst,
        kScrollPaintPhaseLast = kScrollPaintPhaseFirst + kPaintPhaseMax,
        kScrollOverflowControls,
        kScrollLast = kScrollOverflowControls,
        kEndScrollFirst,
        kEndScrollLast = kEndScrollFirst + kScrollLast - kScrollFirst,

        kTransform3DFirst,
        kTransform3DElementTransform = kTransform3DFirst,
        kTransform3DLast = kTransform3DElementTransform,
        kEndTransform3DFirst,
        kEndTransform3DLast = kEndTransform3DFirst + kTransform3DLast - kTransform3DFirst,

        kBeginFilter,
        kEndFilter,
        kBeginCompositing,
        kEndCompositing,
        kBeginTransform,
        kEndTransform,
        kBeginClipPath,
        kEndClipPath,

        kSubsequence,
        kEndSubsequence,

        kUninitializedType,
        kTypeLast = kUninitializedType
    };

    static_assert(kTableCollapsedBorderBase >= kTableCollapsedBorderUnalignedBase, "TableCollapsedBorder types overlap with other types");
    static_assert((kTableCollapsedBorderBase & 0xf) == 0, "The lowest 4 bits of TableCollapsedBorderBase should be zero");
    // Bits or'ed onto TableCollapsedBorderBase to generate a real table collapsed border type.
    enum TableCollapsedBorderSides {
        TableCollapsedBorderTop = 1 << 0,
        TableCollapsedBorderRight = 1 << 1,
        TableCollapsedBorderBottom = 1 << 2,
        TableCollapsedBorderLeft = 1 << 3,
    };

    DisplayItem(const DisplayItemClient& client, Type type, size_t derivedSize)
        : m_client(&client)
        , m_type(type)
        , m_derivedSize(derivedSize)
        , m_skippedCache(false)
#ifndef NDEBUG
        , m_clientDebugString(client.debugName())
#endif
    {
        // derivedSize must fit in m_derivedSize.
        // If it doesn't, enlarge m_derivedSize and fix this assert.
        ASSERT_WITH_SECURITY_IMPLICATION(derivedSize < (1 << 8));
        ASSERT_WITH_SECURITY_IMPLICATION(derivedSize >= sizeof(*this));
    }

    virtual ~DisplayItem() { }

    // Ids are for matching new DisplayItems with existing DisplayItems.
    struct Id {
        DISALLOW_NEW_EXCEPT_PLACEMENT_NEW();
        Id(const DisplayItemClient& client, const Type type)
            : client(client)
            , type(type) { }

        const DisplayItemClient& client;
        const Type type;
    };

    Id getId() const { return Id(*m_client, m_type); }

    virtual void replay(GraphicsContext&) const { }

    const DisplayItemClient& client() const { ASSERT(m_client); return *m_client; }
    Type getType() const { return m_type; }

    // Size of this object in memory, used to move it with memcpy.
    // This is not sizeof(*this), because it needs to account for the size of
    // the derived class (i.e. runtime type). Derived classes are expected to
    // supply this to the DisplayItem constructor.
    size_t derivedSize() const { return m_derivedSize; }

    // For PaintController only. Painters should use DisplayItemCacheSkipper instead.
    void setSkippedCache() { m_skippedCache = true; }
    bool skippedCache() const { return m_skippedCache; }

    // TODO(wkorman): Only DrawingDisplayItem needs the visual rect argument.
    // Consider refactoring class hierarchy to make this more explicit.
    virtual void appendToWebDisplayItemList(const IntRect&, WebDisplayItemList*) const { }

    // See comments of enum Type for usage of the following macros.
#define DEFINE_CATEGORY_METHODS(Category) \
    static bool is##Category##Type(Type type) { return type >= k##Category##First && type <= k##Category##Last; } \
    bool is##Category() const { return is##Category##Type(getType()); }

#define DEFINE_CONVERSION_METHODS(Category1, category1, Category2, category2) \
    static Type category1##TypeTo##Category2##Type(Type type) \
    { \
        static_assert(k##Category1##Last - k##Category1##First == k##Category2##Last - k##Category2##First, \
            "Categories " #Category1 " and " #Category2 " should have same number of enum values. See comments of DisplayItem::Type"); \
        ASSERT(is##Category1##Type(type)); \
        return static_cast<Type>(type - k##Category1##First + k##Category2##First); \
    } \
    static Type category2##TypeTo##Category1##Type(Type type) \
    { \
        ASSERT(is##Category2##Type(type)); \
        return static_cast<Type>(type - k##Category2##First + k##Category1##First); \
    }

#define DEFINE_PAIRED_CATEGORY_METHODS(Category, category) \
    DEFINE_CATEGORY_METHODS(Category) \
    DEFINE_CATEGORY_METHODS(End##Category) \
    DEFINE_CONVERSION_METHODS(Category, category, End##Category, end##Category)

#define DEFINE_PAINT_PHASE_CONVERSION_METHOD(Category) \
    static Type paintPhaseTo##Category##Type(int paintPhase) \
    { \
        static_assert(k##Category##PaintPhaseLast - k##Category##PaintPhaseFirst == k##PaintPhaseMax, \
            "Invalid paint-phase-based category " #Category ". See comments of DisplayItem::Type"); \
        return static_cast<Type>(paintPhase + k##Category##PaintPhaseFirst); \
    }

    DEFINE_CATEGORY_METHODS(Drawing)
    DEFINE_PAINT_PHASE_CONVERSION_METHOD(Drawing)

    DEFINE_CATEGORY_METHODS(ForeignLayer)

    DEFINE_PAIRED_CATEGORY_METHODS(Clip, clip)
    DEFINE_PAINT_PHASE_CONVERSION_METHOD(ClipLayerFragment)
    DEFINE_PAINT_PHASE_CONVERSION_METHOD(ClipBox)
    DEFINE_PAINT_PHASE_CONVERSION_METHOD(ClipColumnBounds)

    DEFINE_PAIRED_CATEGORY_METHODS(FloatClip, floatClip)
    DEFINE_PAINT_PHASE_CONVERSION_METHOD(FloatClip)

    DEFINE_PAIRED_CATEGORY_METHODS(Scroll, scroll)
    DEFINE_PAINT_PHASE_CONVERSION_METHOD(Scroll)

    DEFINE_PAIRED_CATEGORY_METHODS(Transform3D, transform3D)

    static bool isCacheableType(Type type) { return isDrawingType(type) || type == kSubsequence; }
    bool isCacheable() const { return !skippedCache() && isCacheableType(m_type); }

    virtual bool isBegin() const { return false; }
    virtual bool isEnd() const { return false; }

#if DCHECK_IS_ON()
    virtual bool isEndAndPairedWith(DisplayItem::Type otherType) const { return false; }
#endif

    virtual bool equals(const DisplayItem& other) const
    {
        return m_client == other.m_client
            && m_type == other.m_type
            && m_derivedSize == other.m_derivedSize
            && m_skippedCache == other.m_skippedCache;
    }

    // True if the client is non-null. Because m_client is const, this should
    // never be false except when we explicitly create a tombstone/"dead display
    // item" as part of moving an item from one list to another (see:
    // DisplayItemList::appendByMoving).
    bool hasValidClient() const { return m_client; }

    virtual bool drawsContent() const { return false; }

    // Override to implement specific analysis strategies.
    virtual void analyzeForGpuRasterization(SkPictureGpuAnalyzer&) const { }

#ifndef NDEBUG
    static WTF::String typeAsDebugString(DisplayItem::Type);
    const WTF::String clientDebugString() const { return m_clientDebugString; }
    void setClientDebugString(const WTF::String& s) { m_clientDebugString = s; }
    WTF::String asDebugString() const;
    virtual void dumpPropertiesAsDebugString(WTF::StringBuilder&) const;
#endif

private:
    // The default DisplayItem constructor is only used by
    // ContiguousContainer::appendByMoving where an invalid DisplaItem is
    // constructed at the source location.
    template <typename T, unsigned alignment> friend class ContiguousContainer;

    DisplayItem()
        : m_client(nullptr)
        , m_type(kUninitializedType)
        , m_derivedSize(sizeof(*this))
        , m_skippedCache(false)
    { }

    const DisplayItemClient* m_client;
    static_assert(kTypeLast < (1 << 16), "DisplayItem::Type should fit in 16 bits");
    const Type m_type : 16;
    const unsigned m_derivedSize : 8; // size of the actual derived class
    unsigned m_skippedCache : 1;

#ifndef NDEBUG
    WTF::String m_clientDebugString;
#endif
};

inline bool operator==(const DisplayItem::Id& a, const DisplayItem::Id& b)
{
    return a.client == b.client && a.type == b.type;
}

inline bool operator!=(const DisplayItem::Id& a, const DisplayItem::Id& b)
{
    return !(a == b);
}

class PLATFORM_EXPORT PairedBeginDisplayItem : public DisplayItem {
protected:
    PairedBeginDisplayItem(const DisplayItemClient& client, Type type, size_t derivedSize) : DisplayItem(client, type, derivedSize) { }

private:
    bool isBegin() const final { return true; }
};

class PLATFORM_EXPORT PairedEndDisplayItem : public DisplayItem {
protected:
    PairedEndDisplayItem(const DisplayItemClient& client, Type type, size_t derivedSize) : DisplayItem(client, type, derivedSize) { }

#if ENABLE(ASSERT)
    bool isEndAndPairedWith(DisplayItem::Type otherType) const override = 0;
#endif

private:
    bool isEnd() const final { return true; }
};

} // namespace blink

#endif // DisplayItem_h