1 /* 2 * Copyright 2022 Google LLC 3 * 4 * Use of this source code is governed by a BSD-style license that can be 5 * found in the LICENSE file. 6 */ 7 8 #ifndef skgpu_graphite_ImageProvider_DEFINED 9 #define skgpu_graphite_ImageProvider_DEFINED 10 11 #include "include/core/SkImage.h" 12 #include "include/core/SkRefCnt.h" 13 14 namespace skgpu::graphite { 15 16 class Recorder; 17 18 /* 19 * This class provides a centralized location for clients to perform any caching of images 20 * they desire. Whenever Graphite encounters an SkImage which is not Graphite-backed 21 * it will call ImageProvider::findOrCreate. The client's derived version of this class should 22 * return a Graphite-backed version of the provided SkImage that meets the specified 23 * requirements. 24 * 25 * Skia requires that 'findOrCreate' return a Graphite-backed image that preserves the 26 * dimensions and alpha type of the original image. The bit depth of the 27 * individual channels can change (e.g., 4444 -> 8888 is allowed) as well as the channels - as 28 * long as the returned image has a superset of the original image's channels 29 * (e.g., 565 -> 8888 opaque is allowed). 30 * 31 * Wrt mipmapping, the returned image can have different mipmap settings than requested. If 32 * mipmapping was requested but not returned, the sampling level will be reduced to linear. 33 * If the requirements are not met by the returned image (modulo the flexibility wrt mipmapping) 34 * Graphite will drop the draw. 35 * 36 * All returned images must be backed by textures that have a TopLeft origin. If Skia is used to 37 * create the texture (e.g. using makeTextureImage) then this is always guaranteed. If the client 38 * returns a texture they created themselves and wrapped in Skia, they must ensure that texture has 39 * a TopLeft origin. 40 * 41 * Note: by default, Graphite will not perform any caching of images 42 * 43 * Threading concerns: 44 * If the same ImageProvider is given to multiple Recorders it is up to the 45 * client to handle any required thread synchronization. This is not limited to just 46 * restricting access to whatever map a derived class may have but extends to ensuring 47 * that an image created on one Recorder has had its creation work submitted before it 48 * is used by any work submitted by another Recording. Please note, this requirement 49 * (re the submission of creation work and image usage on different threads) is common to all 50 * graphite SkImages and isn't unique to SkImages returned by the ImageProvider. 51 * 52 * TODO(b/240996632): add documentation re shutdown order. 53 * TODO(b/240997067): add unit tests 54 */ 55 class SK_API ImageProvider : public SkRefCnt { 56 public: 57 // If the client's derived class already has a Graphite-backed image that has the same 58 // contents as 'image' and meets the requirements, then it can be returned. 59 // makeTextureImage can always be called to create an acceptable Graphite-backed image 60 // which could then be cached. 61 virtual sk_sp<SkImage> findOrCreate(Recorder* recorder, 62 const SkImage* image, 63 SkImage::RequiredProperties) = 0; 64 }; 65 66 } // namespace skgpu::graphite 67 68 #endif // skgpu_graphite_ImageProvider_DEFINED 69