1 // Copyright 2015 The Chromium 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 CC_TILES_IMAGE_DECODE_CACHE_H_
6 #define CC_TILES_IMAGE_DECODE_CACHE_H_
7 
8 #include "base/memory/ref_counted.h"
9 #include "cc/base/devtools_instrumentation.h"
10 #include "cc/cc_export.h"
11 #include "cc/paint/decoded_draw_image.h"
12 #include "cc/paint/draw_image.h"
13 #include "cc/raster/tile_task.h"
14 #include "cc/tiles/image_decode_cache_utils.h"
15 #include "cc/tiles/tile_priority.h"
16 
17 namespace cc {
18 
19 // ImageDecodeCache is responsible for generating decode tasks, decoding
20 // images, storing images in cache, and being able to return the decoded images
21 // when requested.
22 
23 // ImageDecodeCache is responsible for the following things:
24 // 1. Given a DrawImage, it can return an TileTask which when run will
25 //    decode and cache the resulting image. If the image does not need a task to
26 //    be decoded, then nullptr will be returned. The return value of the
27 //    function indicates whether the image was or is going to be locked, so an
28 //    unlock will be required.
29 // 2. Given a cache key and a DrawImage, it can decode the image and store it in
30 //    the cache. Note that it is important that this function is only accessed
31 //    via an image decode task.
32 // 3. Given a DrawImage, it can return a DecodedDrawImage, which represented the
33 //    decoded version of the image. Note that if the image is not in the cache
34 //    and it needs to be scaled/decoded, then this decode will happen as part of
35 //    getting the image. As such, this should only be accessed from a raster
36 //    thread.
37 class CC_EXPORT ImageDecodeCache {
38  public:
39   enum class TaskType { kInRaster, kOutOfRaster };
40 
41   // This information should be used strictly in tracing, UMA, and any other
42   // reporting systems.
43   struct TracingInfo {
TracingInfoTracingInfo44     TracingInfo(uint64_t prepare_tiles_id,
45                 TilePriority::PriorityBin requesting_tile_bin,
46                 TaskType task_type)
47         : prepare_tiles_id(prepare_tiles_id),
48           requesting_tile_bin(requesting_tile_bin),
49           task_type(task_type) {}
50     TracingInfo() = default;
51 
52     // ID for the current prepare tiles call.
53     const uint64_t prepare_tiles_id = 0;
54 
55     // The bin of the tile that caused this image to be requested.
56     const TilePriority::PriorityBin requesting_tile_bin = TilePriority::NOW;
57 
58     // Whether the decode is requested as a part of tile rasterization.
59     const TaskType task_type = TaskType::kInRaster;
60   };
61 
62   static devtools_instrumentation::ScopedImageDecodeTask::TaskType
ToScopedTaskType(TaskType task_type)63   ToScopedTaskType(TaskType task_type) {
64     using ScopedTaskType =
65         devtools_instrumentation::ScopedImageDecodeTask::TaskType;
66     switch (task_type) {
67       case TaskType::kInRaster:
68         return ScopedTaskType::kInRaster;
69       case TaskType::kOutOfRaster:
70         return ScopedTaskType::kOutOfRaster;
71     }
72     NOTREACHED();
73     return ScopedTaskType::kInRaster;
74   }
75 
76   static devtools_instrumentation::ScopedImageDecodeTask::ImageType
ToScopedImageType(ImageType image_type)77   ToScopedImageType(ImageType image_type) {
78     using ScopedImageType =
79         devtools_instrumentation::ScopedImageDecodeTask::ImageType;
80     switch (image_type) {
81       case ImageType::kAVIF:
82         return ScopedImageType::kAvif;
83       case ImageType::kBMP:
84         return ScopedImageType::kBmp;
85       case ImageType::kGIF:
86         return ScopedImageType::kGif;
87       case ImageType::kICO:
88         return ScopedImageType::kIco;
89       case ImageType::kJPEG:
90         return ScopedImageType::kJpeg;
91       case ImageType::kPNG:
92         return ScopedImageType::kPng;
93       case ImageType::kWEBP:
94         return ScopedImageType::kWebP;
95       case ImageType::kInvalid:
96         return ScopedImageType::kOther;
97     }
98   }
99 
~ImageDecodeCache()100   virtual ~ImageDecodeCache() {}
101 
102   struct CC_EXPORT TaskResult {
103     explicit TaskResult(bool need_unref,
104                         bool is_at_raster_decode,
105                         bool can_do_hardware_accelerated_decode);
106     explicit TaskResult(scoped_refptr<TileTask> task,
107                         bool can_do_hardware_accelerated_decode);
108     TaskResult(const TaskResult& result);
109     ~TaskResult();
110 
111     scoped_refptr<TileTask> task;
112     bool need_unref = false;
113     bool is_at_raster_decode = false;
114     bool can_do_hardware_accelerated_decode = false;
115   };
116   // Fill in an TileTask which will decode the given image when run. In
117   // case the image is already cached, fills in nullptr. Returns true if the
118   // image needs to be unreffed when the caller is finished with it.
119   //
120   // This is called by the tile manager (on the compositor thread) when creating
121   // a raster task.
122   virtual TaskResult GetTaskForImageAndRef(const DrawImage& image,
123                                            const TracingInfo& tracing_info) = 0;
124   // Similar to GetTaskForImageAndRef, except that it returns tasks that are not
125   // meant to be run as part of raster. That is, this is part of a predecode
126   // API. Note that this should only return a task responsible for decoding (and
127   // not uploading), since it will be run on a worker thread which may not have
128   // the right GPU context for upload.
129   virtual TaskResult GetOutOfRasterDecodeTaskForImageAndRef(
130       const DrawImage& image) = 0;
131 
132   // Unrefs an image. When the tile is finished, this should be called for every
133   // GetTaskForImageAndRef call that returned true.
134   virtual void UnrefImage(const DrawImage& image) = 0;
135 
136   // Returns a decoded draw image. This may cause a decode if the image was not
137   // predecoded.
138   //
139   // This is called by a raster task (on a worker thread) when an image is
140   // required.
141   //
142   // TODO(khushalsagar/vmpstr): Since the cache knows if it's a video frame, it
143   // should discard any frames from the same source not in use in the
144   // compositor.
145   virtual DecodedDrawImage GetDecodedImageForDraw(const DrawImage& image) = 0;
146   // Unrefs an image. This should be called for every GetDecodedImageForDraw
147   // when the draw with the image is finished.
148   virtual void DrawWithImageFinished(const DrawImage& image,
149                                      const DecodedDrawImage& decoded_image) = 0;
150 
151   // This function informs the cache that now is a good time to clean up
152   // memory. This is called periodically from the compositor thread.
153   virtual void ReduceCacheUsage() = 0;
154 
155   // This function informs the cache that we are hidden and should not be
156   // retaining cached resources longer than needed.
157   virtual void SetShouldAggressivelyFreeResources(
158       bool aggressively_free_resources) = 0;
159 
160   // Clears all elements from the cache.
161   virtual void ClearCache() = 0;
162 
163   // Returns the maximum amount of memory we would be able to lock. This ignores
164   // any temporary states, such as throttled, and return the maximum possible
165   // memory. It is used as an esimate of whether an image can fit into the
166   // locked budget before creating a task.
167   virtual size_t GetMaximumMemoryLimitBytes() const = 0;
168 
169   // Returns true if the cache should be used for |image|. In certain cases the
170   // image can directly be used for raster (for instance bitmaps in a software
171   // draw).
172   virtual bool UseCacheForDrawImage(const DrawImage& image) const = 0;
173 
174   // Should be called periodically to record statistics about cache use and
175   // performance.
176   virtual void RecordStats() = 0;
177 };
178 
179 }  // namespace cc
180 
181 #endif  // CC_TILES_IMAGE_DECODE_CACHE_H_
182