1// Copyright 2013 The Flutter Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5#ifndef FLUTTER_DISPLAY_LIST_DISPLAY_LIST_ATTRIBUTES_H_
6#define FLUTTER_DISPLAY_LIST_DISPLAY_LIST_ATTRIBUTES_H_
7
8#include <memory>
9
10namespace flutter {
11
12// ===========================================================================
13
14// The base class for a family of DisplayList attribute classes.
15//
16// This class is designed to support the following properties for any
17// attribute to facilitate the storage of the attribute in a DisplayList
18// and for use in code that inspects or creates DisplayList objects:
19//
20// - Typed:
21// Even though most references and pointers are passed around as the
22// attribute's base class, a Type property can be queried using the |type|
23// method to determine which type of the attribute is being used. For
24// example, the Blend type of ColorFilter will return DlColorFilter::kBlend
25// from its type method.
26//
27// - Inspectable:
28// Any parameters required to full specify the action of the attribute are
29// provided on the type-specific classes.
30//
31// - Safely Downcast:
32// For the subclasses that have specific data to query, methods are
33// provided to safely downcast the reference for inspection. The down
34// casting method will either return a pointer to the instance with
35// its type-specific class type, or nullptr if it is executed on the
36// wrong type of instance.
37// (eg. DlColorFilter::asBlend() or DlMaskFilter::asBlur())
38//
39// - Immutable:
40// Neither the base class or any of the subclasses specify any mutation
41// methods. Instances are often passed around as const as a reminder,
42// but the classes have no mutation methods anyway.
43//
44// - Flat and Embeddable:
45// Bulk freed + bulk compared + zero memory fragmentation.
46//
47// All of these classes are designed to be stored in the DisplayList
48// buffer allocated in-line with the rest of the data to avoid dangling
49// pointers that require explicit freeing when the DisplayList goes
50// away, or that fragment the memory needed to read the operations in
51// the DisplayList. Furthermore, the data in the classes can be bulk
52// compared using a |memcmp| when performing a |DisplayList::Equals|.
53//
54// - Passed by Pointer:
55// The data shared via the |DlOpReceiver::set<Attribute>| calls are stored
56// in the buffer itself and so their lifetime is controlled by the
57// DisplayList. That memory cannot be shared as by a |shared_ptr|
58// because the memory may be freed outside the control of the shared
59// pointer. Creating a shared version of the object would require a
60// new instantiation which we'd like to avoid on every dispatch call,
61// so a raw (const) pointer is shared in those dispatch calls instead,
62// with all of the responsibilities of non-ownership in the called method.
63//
64// But, for methods that need to keep a copy of the data...
65//
66// - Shared_Ptr-able:
67// The classes support a method to return a |std::shared_ptr| version of
68// themselves, safely instantiating a new copy of the object into a
69// shared_ptr using |std::make_shared|. For those receiver objects
70// that may want to hold on to the contents of the object (typically
71// in a |current_attribute_| field), they can obtain a shared_ptr
72// copy safely and easily using the |shared| method.
73
74// ===========================================================================
75
76// |D| is the base type for the attribute
77// (i.e. DlColorFilter, etc.)
78// |T| is the enum that describes the specific subclasses
79// (i.e DlColorFilterType, etc.)
80template <class D, typename T>
81class DlAttribute {
82 public:
83 // Return the recognized specific type of the attribute.
84 virtual T type() const = 0;
85
86 // Return the size of the instantiated data (typically used to allocate)
87 // storage in the DisplayList buffer.
88 virtual size_t size() const = 0;
89
90 // Return a shared version of |this| attribute. The |shared_ptr| returned
91 // will reference a copy of this object so that the lifetime of the shared
92 // version is not tied to the storage of this particular instance.
93 virtual std::shared_ptr<D> shared() const = 0;
94
95 // Perform a content aware |==| comparison of the Attribute.
96 bool operator==(D const& other) const {
97 return type() == other.type() && equals_(other);
98 }
99 // Perform a content aware |!=| comparison of the Attribute.
100 bool operator!=(D const& other) const { return !(*this == other); }
101
102 virtual ~DlAttribute() = default;
103
104 protected:
105 // Virtual comparison method to support |==| and |!=|.
106 virtual bool equals_(D const& other) const = 0;
107};
108
109} // namespace flutter
110
111#endif // FLUTTER_DISPLAY_LIST_DISPLAY_LIST_ATTRIBUTES_H_
112

source code of flutter_engine/flutter/display_list/dl_attributes.h