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*
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.
27  // A platform-specific GPU surface-backed texture.
30 
31 // Supported GPU surface types.
32 typedef enum {
33  // Uninitialized.
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
39  // A |ID3D11Texture2D| (Windows only).
42 
43 // Supported pixel formats.
44 typedef enum {
45  // Uninitialized.
47  // Represents a 32-bit RGBA color format with 8 bits each for red, green, blue
48  // and alpha.
50  // Represents a 32-bit BGRA color format with 8 bits each for blue, green, red
51  // and alpha.
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|.
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|.
97  // The pixel format which might be optional depending on the surface type.
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|.
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* (
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* (
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.
133  // Opaque data that will get passed to the provided |callback|.
134  void* user_data;
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|)
145  // The callback used by the engine to obtain the surface descriptor.
147  // Opaque data that will get passed to the provided |callback|.
148  void* user_data;
150 
151 typedef struct {
153  union {
156  };
158 
159 // Registers a new texture with the Flutter engine and returns the texture ID.
160 // This function can be called from any thread.
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.
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
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