| Flutter macOS Embedder |

flutter_texture_registrar.h
Go to the documentation of this file.
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_SHELL_PLATFORM_COMMON_PUBLIC_FLUTTER_TEXTURE_REGISTRAR_H_
6 #define FLUTTER_SHELL_PLATFORM_COMMON_PUBLIC_FLUTTER_TEXTURE_REGISTRAR_H_
7
8 #include <stddef.h>
9 #include <stdint.h>
10
11 #include "flutter_export.h"
12
13 #if defined(__cplusplus)
14 extern "C" {
15 #endif
16
17 struct FlutterDesktopTextureRegistrar;
18 // Opaque reference to a texture registrar.
19 typedef struct FlutterDesktopTextureRegistrar*
20 FlutterDesktopTextureRegistrarRef;
21
22 // Possible values for the type specified in FlutterDesktopTextureInfo.
23 // Additional types may be added in the future.
24 typedef enum {
25 // A Pixel buffer-based texture.
26 kFlutterDesktopPixelBufferTexture,
27 // A platform-specific GPU surface-backed texture.
28 kFlutterDesktopGpuSurfaceTexture
29 } FlutterDesktopTextureType;
30
31 // Supported GPU surface types.
32 typedef enum {
33 // Uninitialized.
34 kFlutterDesktopGpuSurfaceTypeNone,
35 // A DXGI shared texture handle (Windows only).
36 // See
37 // https://docs.microsoft.com/en-us/windows/win32/api/dxgi/nf-dxgi-idxgiresource-getsharedhandle
38 kFlutterDesktopGpuSurfaceTypeDxgiSharedHandle,
39 // A |ID3D11Texture2D| (Windows only).
40 kFlutterDesktopGpuSurfaceTypeD3d11Texture2D
41 } FlutterDesktopGpuSurfaceType;
42
43 // Supported pixel formats.
44 typedef enum {
45 // Uninitialized.
46 kFlutterDesktopPixelFormatNone,
47 // Represents a 32-bit RGBA color format with 8 bits each for red, green, blue
48 // and alpha.
49 kFlutterDesktopPixelFormatRGBA8888,
50 // Represents a 32-bit BGRA color format with 8 bits each for blue, green, red
51 // and alpha.
52 kFlutterDesktopPixelFormatBGRA8888
53 } FlutterDesktopPixelFormat;
54
55 // An image buffer object.
56 typedef struct {
57 // The pixel data buffer.
58 const uint8_t* buffer;
59 // Width of the pixel buffer.
60 size_t width;
61 // Height of the pixel buffer.
62 size_t height;
63 // An optional callback that gets invoked when the |buffer| can be released.
64 void (*release_callback)(void* release_context);
65 // Opaque data passed to |release_callback|.
66 void* release_context;
67 } FlutterDesktopPixelBuffer;
68
69 // A GPU surface descriptor.
70 typedef struct {
71 // The size of this struct. Must be
72 // sizeof(FlutterDesktopGpuSurfaceDescriptor).
73 size_t struct_size;
74 // The surface handle. The expected type depends on the
75 // |FlutterDesktopGpuSurfaceType|.
76 //
77 // Provide a |ID3D11Texture2D*| when using
78 // |kFlutterDesktopGpuSurfaceTypeD3d11Texture2D| or a |HANDLE| when using
79 // |kFlutterDesktopGpuSurfaceTypeDxgiSharedHandle|.
80 //
81 // The referenced resource needs to stay valid until it has been opened by
82 // Flutter. Consider incrementing the resource's reference count in the
83 // |FlutterDesktopGpuSurfaceTextureCallback| and registering a
84 // |release_callback| for decrementing the reference count once it has been
85 // opened.
86 void* handle;
87 // The physical width.
88 size_t width;
89 // The physical height.
90 size_t height;
91 // The visible width.
92 // It might be less or equal to the physical |width|.
93 size_t visible_width;
94 // The visible height.
95 // It might be less or equal to the physical |height|.
96 size_t visible_height;
97 // The pixel format which might be optional depending on the surface type.
98 FlutterDesktopPixelFormat format;
99 // An optional callback that gets invoked when the |handle| has been opened.
100 void (*release_callback)(void* release_context);
101 // Opaque data passed to |release_callback|.
102 void* release_context;
103 } FlutterDesktopGpuSurfaceDescriptor;
104
105 // The pixel buffer copy callback definition provided to
106 // the Flutter engine to copy the texture.
107 // It is invoked with the intended surface size specified by |width| and
108 // |height| and the |user_data| held by
109 // |FlutterDesktopPixelBufferTextureConfig|.
110 //
111 // As this is usually called from the render thread, the callee must take
112 // care of proper synchronization. It also needs to be ensured that the
113 // returned |FlutterDesktopPixelBuffer| isn't released prior to unregistering
114 // the corresponding texture.
115 typedef const FlutterDesktopPixelBuffer* (
116 *FlutterDesktopPixelBufferTextureCallback)(size_t width,
117 size_t height,
118 void* user_data);
119
120 // The GPU surface callback definition provided to the Flutter engine to obtain
121 // the surface. It is invoked with the intended surface size specified by
122 // |width| and |height| and the |user_data| held by
123 // |FlutterDesktopGpuSurfaceTextureConfig|.
124 typedef const FlutterDesktopGpuSurfaceDescriptor* (
125 *FlutterDesktopGpuSurfaceTextureCallback)(size_t width,
126 size_t height,
127 void* user_data);
128
129 // An object used to configure pixel buffer textures.
130 typedef struct {
131 // The callback used by the engine to copy the pixel buffer object.
132 FlutterDesktopPixelBufferTextureCallback callback;
133 // Opaque data that will get passed to the provided |callback|.
134 void* user_data;
135 } FlutterDesktopPixelBufferTextureConfig;
136
137 // An object used to configure GPU-surface textures.
138 typedef struct {
139 // The size of this struct. Must be
140 // sizeof(FlutterDesktopGpuSurfaceTextureConfig).
141 size_t struct_size;
142 // The concrete surface type (e.g.
143 // |kFlutterDesktopGpuSurfaceTypeDxgiSharedHandle|)
144 FlutterDesktopGpuSurfaceType type;
145 // The callback used by the engine to obtain the surface descriptor.
146 FlutterDesktopGpuSurfaceTextureCallback callback;
147 // Opaque data that will get passed to the provided |callback|.
148 void* user_data;
149 } FlutterDesktopGpuSurfaceTextureConfig;
150
151 typedef struct {
152 FlutterDesktopTextureType type;
153 union {
154 FlutterDesktopPixelBufferTextureConfig pixel_buffer_config;
155 FlutterDesktopGpuSurfaceTextureConfig gpu_surface_config;
156 };
157 } FlutterDesktopTextureInfo;
158
159 // Registers a new texture with the Flutter engine and returns the texture ID.
160 // This function can be called from any thread.
161 FLUTTER_EXPORT int64_t FlutterDesktopTextureRegistrarRegisterExternalTexture(
162 FlutterDesktopTextureRegistrarRef texture_registrar,
163 const FlutterDesktopTextureInfo* info);
164
165 // Asynchronously unregisters the texture identified by |texture_id| from the
166 // Flutter engine.
167 // An optional |callback| gets invoked upon completion.
168 // This function can be called from any thread.
169 FLUTTER_EXPORT void FlutterDesktopTextureRegistrarUnregisterExternalTexture(
170 FlutterDesktopTextureRegistrarRef texture_registrar,
171 int64_t texture_id,
172 void (*callback)(void* user_data),
173 void* user_data);
174
175 // Marks that a new texture frame is available for a given |texture_id|.
176 // Returns true on success or false if the specified texture doesn't exist.
177 // This function can be called from any thread.
178 FLUTTER_EXPORT bool
179 FlutterDesktopTextureRegistrarMarkExternalTextureFrameAvailable(
180 FlutterDesktopTextureRegistrarRef texture_registrar,
181 int64_t texture_id);
182
183 #if defined(__cplusplus)
184 } // extern "C"
185 #endif
186
187 #endif // FLUTTER_SHELL_PLATFORM_COMMON_PUBLIC_FLUTTER_TEXTURE_REGISTRAR_H_
FlutterDesktopGpuSurfaceDescriptor::format
FlutterDesktopPixelFormat format
Definition: flutter_texture_registrar.h:98
kFlutterDesktopGpuSurfaceTexture
@ kFlutterDesktopGpuSurfaceTexture
Definition: flutter_texture_registrar.h:28
FlutterDesktopTextureRegistrarRegisterExternalTexture
FLUTTER_EXPORT int64_t FlutterDesktopTextureRegistrarRegisterExternalTexture(FlutterDesktopTextureRegistrarRef texture_registrar, const FlutterDesktopTextureInfo *info)
FlutterDesktopPixelBuffer
Definition: flutter_texture_registrar.h:56
FLUTTER_EXPORT
#define FLUTTER_EXPORT
Definition: flutter_export.h:23
user_data
void * user_data
Definition: texture_registrar_unittests.cc:27
FlutterDesktopPixelBufferTextureConfig::user_data
void * user_data
Definition: flutter_texture_registrar.h:134
FlutterDesktopGpuSurfaceDescriptor::visible_width
size_t visible_width
Definition: flutter_texture_registrar.h:93
kFlutterDesktopGpuSurfaceTypeNone
@ kFlutterDesktopGpuSurfaceTypeNone
Definition: flutter_texture_registrar.h:34
FlutterDesktopGpuSurfaceTextureConfig::user_data
void * user_data
Definition: flutter_texture_registrar.h:148
FlutterDesktopPixelBufferTextureConfig::callback
FlutterDesktopPixelBufferTextureCallback callback
Definition: flutter_texture_registrar.h:132
FlutterDesktopTextureType
FlutterDesktopTextureType
Definition: flutter_texture_registrar.h:24
kFlutterDesktopPixelFormatBGRA8888
@ kFlutterDesktopPixelFormatBGRA8888
Definition: flutter_texture_registrar.h:52
FlutterDesktopGpuSurfaceType
FlutterDesktopGpuSurfaceType
Definition: flutter_texture_registrar.h:32
FlutterDesktopTextureInfo::type
FlutterDesktopTextureType type
Definition: flutter_texture_registrar.h:152
FlutterDesktopPixelFormat
FlutterDesktopPixelFormat
Definition: flutter_texture_registrar.h:44
FlutterDesktopGpuSurfaceDescriptor::visible_height
size_t visible_height
Definition: flutter_texture_registrar.h:96
FlutterDesktopGpuSurfaceDescriptor::release_context
void * release_context
Definition: flutter_texture_registrar.h:102
FlutterDesktopTextureRegistrarRef
struct FlutterDesktopTextureRegistrar * FlutterDesktopTextureRegistrarRef
Definition: flutter_texture_registrar.h:19
FlutterDesktopGpuSurfaceTextureConfig::struct_size
size_t struct_size
Definition: flutter_texture_registrar.h:141
FlutterDesktopTextureInfo::pixel_buffer_config
FlutterDesktopPixelBufferTextureConfig pixel_buffer_config
Definition: flutter_texture_registrar.h:154
FlutterDesktopGpuSurfaceDescriptor::height
size_t height
Definition: flutter_texture_registrar.h:90
FlutterDesktopGpuSurfaceTextureConfig::type
FlutterDesktopGpuSurfaceType type
Definition: flutter_texture_registrar.h:144
FlutterDesktopTextureInfo
Definition: flutter_texture_registrar.h:151
FlutterDesktopPixelBufferTextureConfig
Definition: flutter_texture_registrar.h:130
FlutterDesktopGpuSurfaceTextureConfig::callback
FlutterDesktopGpuSurfaceTextureCallback callback
Definition: flutter_texture_registrar.h:146
FlutterDesktopPixelBuffer::release_context
void * release_context
Definition: flutter_texture_registrar.h:66
FlutterDesktopGpuSurfaceDescriptor
Definition: flutter_texture_registrar.h:70
FlutterDesktopPixelBufferTextureCallback
const typedef FlutterDesktopPixelBuffer *(* FlutterDesktopPixelBufferTextureCallback)(size_t width, size_t height, void *user_data)
Definition: flutter_texture_registrar.h:116
kFlutterDesktopGpuSurfaceTypeD3d11Texture2D
@ kFlutterDesktopGpuSurfaceTypeD3d11Texture2D
Definition: flutter_texture_registrar.h:40
FlutterDesktopTextureInfo::gpu_surface_config
FlutterDesktopGpuSurfaceTextureConfig gpu_surface_config
Definition: flutter_texture_registrar.h:155
FlutterDesktopPixelBuffer::buffer
const uint8_t * buffer
Definition: flutter_texture_registrar.h:58
kFlutterDesktopGpuSurfaceTypeDxgiSharedHandle
@ kFlutterDesktopGpuSurfaceTypeDxgiSharedHandle
Definition: flutter_texture_registrar.h:38
flutter_export.h
FlutterDesktopTextureRegistrarUnregisterExternalTexture
FLUTTER_EXPORT void FlutterDesktopTextureRegistrarUnregisterExternalTexture(FlutterDesktopTextureRegistrarRef texture_registrar, int64_t texture_id, void(*callback)(void *user_data), void *user_data)
FlutterDesktopGpuSurfaceDescriptor::handle
void * handle
Definition: flutter_texture_registrar.h:86
FlutterDesktopGpuSurfaceTextureConfig
Definition: flutter_texture_registrar.h:138
FlutterDesktopTextureRegistrarMarkExternalTextureFrameAvailable
FLUTTER_EXPORT bool FlutterDesktopTextureRegistrarMarkExternalTextureFrameAvailable(FlutterDesktopTextureRegistrarRef texture_registrar, int64_t texture_id)
FlutterDesktopPixelBuffer::width
size_t width
Definition: flutter_texture_registrar.h:60
FlutterDesktopGpuSurfaceTextureCallback
const typedef FlutterDesktopGpuSurfaceDescriptor *(* FlutterDesktopGpuSurfaceTextureCallback)(size_t width, size_t height, void *user_data)
Definition: flutter_texture_registrar.h:125
FlutterDesktopGpuSurfaceDescriptor::struct_size
size_t struct_size
Definition: flutter_texture_registrar.h:73
texture_id
int64_t texture_id
Definition: texture_registrar_unittests.cc:24
FlutterDesktopGpuSurfaceDescriptor::width
size_t width
Definition: flutter_texture_registrar.h:88
kFlutterDesktopPixelFormatNone
@ kFlutterDesktopPixelFormatNone
Definition: flutter_texture_registrar.h:46
kFlutterDesktopPixelBufferTexture
@ kFlutterDesktopPixelBufferTexture
Definition: flutter_texture_registrar.h:26
FlutterDesktopPixelBuffer::height
size_t height
Definition: flutter_texture_registrar.h:62
kFlutterDesktopPixelFormatRGBA8888
@ kFlutterDesktopPixelFormatRGBA8888
Definition: flutter_texture_registrar.h:49