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 SkSurfaceGanesh_DEFINED
9 #define SkSurfaceGanesh_DEFINED
10
11 #include "include/core/SkImageInfo.h"
12 #include "include/core/SkRefCnt.h"
13 #include "include/core/SkSurface.h"
14 #include "include/gpu/ganesh/GrTypes.h"
15 #include "include/private/base/SkAPI.h"
16
17 class GrBackendRenderTarget;
18 class GrBackendTexture;
19 class GrRecordingContext;
20 class SkColorSpace;
21 class GrSurfaceCharacterization;
22 class SkSurfaceProps;
23 enum SkColorType : int;
24 namespace skgpu {
25 enum class Budgeted : bool;
26 }
27
28 namespace SkSurfaces {
29
30 /** Caller data passed to RenderTarget/TextureReleaseProc; may be nullptr. */
31 using ReleaseContext = void*;
32
33 /** User function called when supplied render target may be deleted. */
34 using RenderTargetReleaseProc = void (*)(ReleaseContext);
35
36 /** User function called when supplied texture may be deleted. */
37 using TextureReleaseProc = void (*)(ReleaseContext);
38
39 /** Returns SkSurface on GPU indicated by context. Allocates memory for
40 pixels, based on the width, height, and SkColorType in SkImageInfo. budgeted
41 selects whether allocation for pixels is tracked by context. imageInfo
42 describes the pixel format in SkColorType, and transparency in
43 SkAlphaType, and color matching in SkColorSpace.
44
45 sampleCount requests the number of samples per pixel.
46 Pass zero to disable multi-sample anti-aliasing. The request is rounded
47 up to the next supported count, or rounded down if it is larger than the
48 maximum supported count.
49
50 surfaceOrigin pins either the top-left or the bottom-left corner to the origin.
51
52 shouldCreateWithMips hints that SkImage returned by makeImageSnapshot() is mip map.
53
54 @param context GPU context
55 @param imageInfo width, height, SkColorType, SkAlphaType, SkColorSpace;
56 width, or height, or both, may be zero
57 @param sampleCount samples per pixel, or 0 to disable full scene anti-aliasing
58 @param surfaceOrigin How to align the pixel data.
59 @param surfaceProps LCD striping orientation and setting for device independent
60 fonts; may be nullptr
61 @param shouldCreateWithMips hint that SkSurface will host mip map images
62 @return SkSurface if all parameters are valid; otherwise, nullptr
63 */
64 SK_API sk_sp<SkSurface> RenderTarget(GrRecordingContext* context,
65 skgpu::Budgeted budgeted,
66 const SkImageInfo& imageInfo,
67 int sampleCount,
68 GrSurfaceOrigin surfaceOrigin,
69 const SkSurfaceProps* surfaceProps,
70 bool shouldCreateWithMips = false,
71 bool isProtected = false);
RenderTarget(GrRecordingContext * context,skgpu::Budgeted budgeted,const SkImageInfo & imageInfo,int sampleCount,const SkSurfaceProps * surfaceProps)72 inline sk_sp<SkSurface> RenderTarget(GrRecordingContext* context,
73 skgpu::Budgeted budgeted,
74 const SkImageInfo& imageInfo,
75 int sampleCount,
76 const SkSurfaceProps* surfaceProps) {
77 return RenderTarget(
78 context, budgeted, imageInfo, sampleCount, kBottomLeft_GrSurfaceOrigin, surfaceProps);
79 }
RenderTarget(GrRecordingContext * context,skgpu::Budgeted budgeted,const SkImageInfo & imageInfo)80 inline sk_sp<SkSurface> RenderTarget(GrRecordingContext* context,
81 skgpu::Budgeted budgeted,
82 const SkImageInfo& imageInfo) {
83 if (!imageInfo.width() || !imageInfo.height()) {
84 return nullptr;
85 }
86 return RenderTarget(context, budgeted, imageInfo, 0, kBottomLeft_GrSurfaceOrigin, nullptr);
87 }
88
89 /** Returns SkSurface on GPU indicated by context that is compatible with the provided
90 characterization. budgeted selects whether allocation for pixels is tracked by context.
91
92 @param context GPU context
93 @param characterization description of the desired SkSurface
94 @return SkSurface if all parameters are valid; otherwise, nullptr
95 */
96 SK_API sk_sp<SkSurface> RenderTarget(GrRecordingContext* context,
97 const GrSurfaceCharacterization& characterization,
98 skgpu::Budgeted budgeted);
99
100 /** Wraps a GPU-backed texture into SkSurface. Caller must ensure the texture is
101 valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
102 creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
103
104 SkSurface is returned if all parameters are valid. backendTexture is valid if
105 its pixel configuration agrees with colorSpace and context; for instance, if
106 backendTexture has an sRGB configuration, then context must support sRGB,
107 and colorSpace must be present. Further, backendTexture width and height must
108 not exceed context capabilities, and the context must be able to support
109 back-end textures.
110
111 Upon success textureReleaseProc is called when it is safe to delete the texture in the
112 backend API (accounting only for use of the texture by this surface). If SkSurface creation
113 fails textureReleaseProc is called before this function returns.
114
115 @param context GPU context
116 @param backendTexture texture residing on GPU
117 @param sampleCnt samples per pixel, or 0 to disable full scene anti-aliasing
118 @param colorSpace range of colors; may be nullptr
119 @param surfaceProps LCD striping orientation and setting for device independent
120 fonts; may be nullptr
121 @param textureReleaseProc function called when texture can be released
122 @param releaseContext state passed to textureReleaseProc
123 @return SkSurface if all parameters are valid; otherwise, nullptr
124 */
125 SK_API sk_sp<SkSurface> WrapBackendTexture(GrRecordingContext* context,
126 const GrBackendTexture& backendTexture,
127 GrSurfaceOrigin origin,
128 int sampleCnt,
129 SkColorType colorType,
130 sk_sp<SkColorSpace> colorSpace,
131 const SkSurfaceProps* surfaceProps,
132 TextureReleaseProc textureReleaseProc = nullptr,
133 ReleaseContext releaseContext = nullptr);
134
135 /** Wraps a GPU-backed buffer into SkSurface. Caller must ensure backendRenderTarget
136 is valid for the lifetime of returned SkSurface.
137
138 SkSurface is returned if all parameters are valid. backendRenderTarget is valid if
139 its pixel configuration agrees with colorSpace and context; for instance, if
140 backendRenderTarget has an sRGB configuration, then context must support sRGB,
141 and colorSpace must be present. Further, backendRenderTarget width and height must
142 not exceed context capabilities, and the context must be able to support
143 back-end render targets.
144
145 Upon success releaseProc is called when it is safe to delete the render target in the
146 backend API (accounting only for use of the render target by this surface). If SkSurface
147 creation fails releaseProc is called before this function returns.
148
149 @param context GPU context
150 @param backendRenderTarget GPU intermediate memory buffer
151 @param colorSpace range of colors
152 @param surfaceProps LCD striping orientation and setting for device independent
153 fonts; may be nullptr
154 @param releaseProc function called when backendRenderTarget can be released
155 @param releaseContext state passed to releaseProc
156 @return SkSurface if all parameters are valid; otherwise, nullptr
157 */
158 SK_API sk_sp<SkSurface> WrapBackendRenderTarget(GrRecordingContext* context,
159 const GrBackendRenderTarget& backendRenderTarget,
160 GrSurfaceOrigin origin,
161 SkColorType colorType,
162 sk_sp<SkColorSpace> colorSpace,
163 const SkSurfaceProps* surfaceProps,
164 RenderTargetReleaseProc releaseProc = nullptr,
165 ReleaseContext releaseContext = nullptr);
166
167 using BackendHandleAccess = SkSurface::BackendHandleAccess;
168
169 /** Retrieves the back-end texture. If SkSurface has no back-end texture, an invalid
170 object is returned. Call GrBackendTexture::isValid to determine if the result
171 is valid.
172
173 The returned GrBackendTexture should be discarded if the SkSurface is drawn to or deleted.
174
175 @return GPU texture reference; invalid on failure
176 */
177 SK_API GrBackendTexture GetBackendTexture(SkSurface*, BackendHandleAccess);
178
179 /** Retrieves the back-end render target. If SkSurface has no back-end render target, an invalid
180 object is returned. Call GrBackendRenderTarget::isValid to determine if the result
181 is valid.
182
183 The returned GrBackendRenderTarget should be discarded if the SkSurface is drawn to
184 or deleted.
185
186 @return GPU render target reference; invalid on failure
187 */
188 SK_API GrBackendRenderTarget GetBackendRenderTarget(SkSurface*, BackendHandleAccess);
189
190 /** If a surface is a Ganesh-backed surface, is being drawn with MSAA, and there is a resolve
191 texture, this call will insert a resolve command into the stream of gpu commands. In order
192 for the resolve to actually have an effect, the work still needs to be flushed and submitted
193 to the GPU after recording the resolve command. If a resolve is not supported or the
194 SkSurface has no dirty work to resolve, then this call is a no-op.
195
196 This call is most useful when the SkSurface is created by wrapping a single sampled gpu
197 texture, but asking Skia to render with MSAA. If the client wants to use the wrapped texture
198 outside of Skia, the only way to trigger a resolve is either to call this command or use
199 GrDirectContext::flush.
200 */
201 SK_API void ResolveMSAA(SkSurface* surface);
ResolveMSAA(const sk_sp<SkSurface> & surface)202 inline void ResolveMSAA(const sk_sp<SkSurface>& surface) {
203 return ResolveMSAA(surface.get());
204 }
205
206 } // namespace SkSurfaces
207
208 namespace skgpu::ganesh {
209 // Clients should strive to call GrDirectContext::flush directly. However, there exist some
210 // places where the GrDirectContext is hard to find, these helpers allow for the flushing of the
211 // provided surface. This is a no-op if the surface is nullptr or not GPU backed.
212 SK_API GrSemaphoresSubmitted Flush(sk_sp<SkSurface>);
213 SK_API GrSemaphoresSubmitted Flush(SkSurface*);
214 SK_API void FlushAndSubmit(sk_sp<SkSurface>);
215 SK_API void FlushAndSubmit(SkSurface*);
216 } // namespace skgpu::ganesh
217
218 #endif
219