1 /* 2 * Copyright 2023 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_Surface_DEFINED 9 #define skgpu_graphite_Surface_DEFINED 10 11 #include "include/core/SkRefCnt.h" 12 #include "include/core/SkSurface.h" 13 #include "include/gpu/GpuTypes.h" 14 15 #include <string_view> 16 17 class SkImage; 18 struct SkImageInfo; 19 20 namespace skgpu::graphite { 21 class BackendTexture; 22 class Recorder; 23 } // namespace skgpu::graphite 24 25 namespace SkSurfaces { 26 using ReleaseContext = void*; 27 using TextureReleaseProc = void (*)(ReleaseContext); 28 29 /** 30 * The 'AsImage' and 'AsImageCopy' API/entry points are currently only available for 31 * Graphite. 32 * 33 * In this API, SkSurface no longer supports copy-on-write behavior. Instead, when creating 34 * an image for a surface, the client must explicitly indicate if a copy should be made. 35 * In both of the below calls the resource backing the surface will never change. 36 * 37 * The 'AsImage' entry point has some major ramifications for the mutability of the 38 * returned SkImage. Since the originating surface and the returned image share the 39 * same backing, care must be taken by the client to ensure that the contents of the image 40 * reflect the desired contents when it is consumed by the gpu. 41 * Note: if the backing GPU buffer isn't textureable this method will return null. Graphite 42 * will not attempt to make a copy. 43 * Note: For 'AsImage', the mipmapping of the image will match that of the source surface. 44 * 45 * The 'AsImageCopy' entry point allows subsetting and the addition of mipmaps (since 46 * a copy is already being made). 47 * 48 * In Graphite, the legacy API call (i.e., makeImageSnapshot) will just always make a copy. 49 */ 50 SK_API sk_sp<SkImage> AsImage(sk_sp<const SkSurface>); 51 SK_API sk_sp<SkImage> AsImageCopy(sk_sp<const SkSurface>, 52 const SkIRect* subset = nullptr, 53 skgpu::Mipmapped = skgpu::Mipmapped::kNo); 54 55 /** 56 * In Graphite, while clients hold a ref on an SkSurface, the backing gpu object does _not_ 57 * count against the budget. Once an SkSurface is freed, the backing gpu object may or may 58 * not become a scratch (i.e., reusable) resource but, if it does, it will be counted against 59 * the budget. 60 */ 61 SK_API sk_sp<SkSurface> RenderTarget(skgpu::graphite::Recorder*, 62 const SkImageInfo& imageInfo, 63 skgpu::Mipmapped = skgpu::Mipmapped::kNo, 64 const SkSurfaceProps* surfaceProps = nullptr, 65 std::string_view label = {}); 66 67 /** 68 * Wraps a GPU-backed texture in an SkSurface. Depending on the backend gpu API, the caller may 69 * be required to ensure the texture is valid for the lifetime of the returned SkSurface. The 70 * required lifetimes for the specific apis are: 71 * Metal: Skia will call retain on the underlying MTLTexture so the caller can drop it once 72 * this call returns. 73 * 74 * SkSurface is returned if all the parameters are valid. The backendTexture is valid if its 75 * format agrees with colorSpace and recorder; for instance, if backendTexture has an sRGB 76 * configuration, then the recorder must support sRGB, and colorSpace must be present. Further, 77 * backendTexture's width and height must not exceed the recorder's capabilities, and the 78 * recorder must be able to support the back-end texture. 79 */ 80 SK_API sk_sp<SkSurface> WrapBackendTexture(skgpu::graphite::Recorder*, 81 const skgpu::graphite::BackendTexture&, 82 SkColorType colorType, 83 sk_sp<SkColorSpace> colorSpace, 84 const SkSurfaceProps* props, 85 TextureReleaseProc = nullptr, 86 ReleaseContext = nullptr, 87 std::string_view label = {}); 88 } // namespace SkSurfaces 89 90 #endif // skgpu_graphite_Surface_DEFINED 91