fre_sys/ffi.rs
1//!
2//! Rust bindings for the ANE C API declared in `<AIR_HOME>/include/FlashRuntimeExtensions.h`.
3//!
4
5
6#![allow(non_snake_case)]
7
8
9use crate::markers::*;
10use crate::types::*;
11
12
13// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Initialization ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
14// ╿ ╿
15/// Defines the signature for native calls that can be invoked via an instance
16/// of the AS3 `ExtensionContext` class.
17///
18/// The return value corresponds to the return value from the AS3 `ExtensionContext.call` method.
19/// Returning an invalid handle value is observed as `null` in AS3.
20///
21pub type FREFunction = unsafe extern "C" fn (
22 ctx: FREContext,
23 functionData: FREData,
24 argc: uint32_t,
25 argv: *const FREObject,
26) -> FREObject;
27
28/// A non-owning descriptor for a registered native function.
29///
30#[derive(Debug)]
31#[repr(C)]
32pub struct FRENamedFunction {
33 pub name: FREStr,
34 pub functionData: FREData,
35 pub function: FREFunction,
36}
37
38/// Defines the signature for the initializer that is called each time a new AS3 `ExtensionContext` object is created.
39///
40/// # Parameters
41///
42/// - `extData`: The extension client data provided to the [`FREInitializer`] function as `extDataToSet`.
43/// - `ctxType`: Pointer to the contextType string (UTF8) as provided to the AS3 `ExtensionContext.createExtensionContext` call.
44/// - `ctx`: The [`FREContext`] being initialized.
45/// - `numFunctionsToSet`: The number of elements in the `functionsToSet` array.
46/// - `functionsToSet`: A pointer to an array of [`FRENamedFunction`] elements.
47///
48pub type FREContextInitializer = unsafe extern "C" fn (
49 extData: FREData,
50 ctxType: FREStr,
51 ctx: FREContext,
52 numFunctionsToSet: *mut uint32_t,
53 functionsToSet: *mut *const FRENamedFunction,
54);
55
56/// Defines the signature for the finalizer that is called each time
57/// an `ExtensionContext` instance is disposed.
58///
59pub type FREContextFinalizer = unsafe extern "C" fn (ctx: FREContext);
60
61/// The initialization function provided by each extension must conform to the following signature.
62///
63/// # Parameters
64///
65/// - `extDataToSet`: Provided for the extension to store per-extension instance data.
66/// For example, if the extension creates globals per-instance,
67/// it can store a pointer to them here.
68/// - `ctxInitializerToSet`: Must be set to a function pointer of type [`FREContextInitializer`].
69/// Will be invoked whenever the AS3 code creates a new context for this extension.
70/// - `ctxFinalizerToSet`: Must be set to a function pointer of type [`FREContextFinalizer`],
71/// or left as [`None`].
72///
73pub type FREInitializer = unsafe extern "C" fn (
74 extDataToSet: *mut FREData,
75 ctxInitializerToSet: *mut FREContextInitializer,
76 ctxFinalizerToSet: *mut Option<FREContextFinalizer>,
77);
78
79/// Called iff the extension is unloaded from the process. Extensions
80/// are not guaranteed to be unloaded; the runtime process may exit without
81/// doing so.
82///
83/// This function is optional and may be omitted by not declaring
84/// `<finalizer>...</finalizer>` in the extension configuration file.
85///
86pub type FREFinalizer = unsafe extern "C" fn (extData: FREData);
87
88
89// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Result Codes ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
90// ╿ ╿
91/// These values must not be changed.
92///
93#[derive(Debug, Clone, Copy, PartialEq, Eq)]
94#[repr(transparent)]
95#[must_use]
96pub struct FREResult(int32_t);
97impl FREResult {
98 pub const FRE_OK: Self = Self(0);
99 pub const FRE_NO_SUCH_NAME: Self = Self(1);
100 pub const FRE_INVALID_OBJECT: Self = Self(2);
101 pub const FRE_TYPE_MISMATCH: Self = Self(3);
102 pub const FRE_ACTIONSCRIPT_ERROR: Self = Self(4);
103 pub const FRE_INVALID_ARGUMENT: Self = Self(5);
104 pub const FRE_READ_ONLY: Self = Self(6);
105 pub const FRE_WRONG_THREAD: Self = Self(7);
106 pub const FRE_ILLEGAL_STATE: Self = Self(8);
107 pub const FRE_INSUFFICIENT_MEMORY: Self = Self(9);
108 pub fn is_ok(self) -> bool {self == Self::FRE_OK}
109 pub fn is_err(self) -> bool {self != Self::FRE_OK}
110 pub fn as_i32(self) -> i32 {self.0}
111 pub fn as_u32(self) -> u32 {self.0 as u32}
112}
113impl std::fmt::Display for FREResult {fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {write!(f, "{:#010X}", self.as_u32())}}
114
115
116// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Context Data ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
117// ╿ ╿
118unsafe extern "C" {
119/// # Returns
120///
121/// - [`FREResult::FRE_OK`]
122/// - [`FREResult::FRE_WRONG_THREAD`]
123/// - [`FREResult::FRE_INVALID_ARGUMENT`] If `nativeData` is null.
124///
125pub fn FREGetContextNativeData(ctx: FREContext, nativeData: *mut FREData) -> FREResult;
126
127/// # Returns
128///
129/// - [`FREResult::FRE_OK`]
130/// - [`FREResult::FRE_INVALID_ARGUMENT`]
131/// - [`FREResult::FRE_WRONG_THREAD`]
132///
133pub fn FRESetContextNativeData(ctx: FREContext, nativeData: FREData) -> FREResult;
134
135/// # Returns
136///
137/// - [`FREResult::FRE_OK`]
138/// - [`FREResult::FRE_WRONG_THREAD`]
139/// - [`FREResult::FRE_INVALID_ARGUMENT`] If `actionScriptData` is null.
140///
141pub fn FREGetContextActionScriptData(ctx: FREContext, actionScriptData: *mut FREObject) -> FREResult;
142
143/// # Returns
144///
145/// - [`FREResult::FRE_OK`]
146/// - [`FREResult::FRE_WRONG_THREAD`]
147///
148pub fn FRESetContextActionScriptData(ctx: FREContext, actionScriptData: FREObject) -> FREResult;
149}
150
151
152// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Primitive Types ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
153// ╿ ╿
154/// These values must not be changed.
155///
156#[derive(Debug, Clone, Copy, PartialEq, Eq)]
157#[repr(transparent)]
158pub struct FREObjectType(int32_t);
159impl FREObjectType {
160 pub const FRE_TYPE_OBJECT: Self = Self(0);
161 pub const FRE_TYPE_NUMBER: Self = Self(1);
162 pub const FRE_TYPE_STRING: Self = Self(2);
163 pub const FRE_TYPE_BYTEARRAY: Self = Self(3);
164 pub const FRE_TYPE_ARRAY: Self = Self(4);
165 pub const FRE_TYPE_VECTOR: Self = Self(5);
166 pub const FRE_TYPE_BITMAPDATA: Self = Self(6);
167 pub const FRE_TYPE_BOOLEAN: Self = Self(7);
168 pub const FRE_TYPE_NULL: Self = Self(8);
169 pub fn is_null(self) -> bool {self == Self::FRE_TYPE_NULL}
170 pub fn as_i32(self) -> i32 {self.0}
171 pub fn as_u32(self) -> u32 {self.0 as u32}
172}
173impl std::fmt::Display for FREObjectType {fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {write!(f, "{:#010X}", self.as_u32())}}
174
175unsafe extern "C" {
176/// # Returns
177///
178/// - [`FREResult::FRE_OK`]
179/// - [`FREResult::FRE_INVALID_OBJECT`]
180/// - [`FREResult::FRE_WRONG_THREAD`]
181/// - [`FREResult::FRE_INVALID_ARGUMENT`] If `objectType` is null.
182///
183pub fn FREGetObjectType(object: FREObject, objectType: *mut FREObjectType) -> FREResult;
184
185/// # Returns
186///
187/// - [`FREResult::FRE_OK`]
188/// - [`FREResult::FRE_TYPE_MISMATCH`]
189/// - [`FREResult::FRE_INVALID_OBJECT`]
190/// - [`FREResult::FRE_INVALID_ARGUMENT`]
191/// - [`FREResult::FRE_WRONG_THREAD`]
192///
193pub fn FREGetObjectAsInt32(object: FREObject, value: *mut int32_t) -> FREResult;
194
195/// # Returns
196///
197/// - [`FREResult::FRE_OK`]
198/// - [`FREResult::FRE_TYPE_MISMATCH`]
199/// - [`FREResult::FRE_INVALID_OBJECT`]
200/// - [`FREResult::FRE_INVALID_ARGUMENT`]
201/// - [`FREResult::FRE_WRONG_THREAD`]
202///
203pub fn FREGetObjectAsUint32(object: FREObject, value: *mut uint32_t) -> FREResult;
204
205/// # Returns
206///
207/// - [`FREResult::FRE_OK`]
208/// - [`FREResult::FRE_TYPE_MISMATCH`]
209/// - [`FREResult::FRE_INVALID_OBJECT`]
210/// - [`FREResult::FRE_INVALID_ARGUMENT`]
211/// - [`FREResult::FRE_WRONG_THREAD`]
212///
213pub fn FREGetObjectAsDouble(object: FREObject, value: *mut double) -> FREResult;
214
215/// # Returns
216///
217/// - [`FREResult::FRE_OK`]
218/// - [`FREResult::FRE_TYPE_MISMATCH`]
219/// - [`FREResult::FRE_INVALID_OBJECT`]
220/// - [`FREResult::FRE_INVALID_ARGUMENT`]
221/// - [`FREResult::FRE_WRONG_THREAD`]
222///
223pub fn FREGetObjectAsBool(object: FREObject, value: *mut FREBoolean) -> FREResult;
224
225/// # Returns
226///
227/// - [`FREResult::FRE_OK`]
228/// - [`FREResult::FRE_INVALID_ARGUMENT`]
229/// - [`FREResult::FRE_WRONG_THREAD`]
230///
231pub fn FRENewObjectFromInt32(value: int32_t, object: *mut FREObject) -> FREResult;
232
233/// # Returns
234///
235/// - [`FREResult::FRE_OK`]
236/// - [`FREResult::FRE_INVALID_ARGUMENT`]
237/// - [`FREResult::FRE_WRONG_THREAD`]
238///
239pub fn FRENewObjectFromUint32(value: uint32_t, object: *mut FREObject) -> FREResult;
240
241/// # Returns
242///
243/// - [`FREResult::FRE_OK`]
244/// - [`FREResult::FRE_INVALID_ARGUMENT`]
245/// - [`FREResult::FRE_WRONG_THREAD`]
246///
247pub fn FRENewObjectFromDouble(value: double, object: *mut FREObject) -> FREResult;
248
249/// # Returns
250///
251/// - [`FREResult::FRE_OK`]
252/// - [`FREResult::FRE_INVALID_ARGUMENT`]
253/// - [`FREResult::FRE_WRONG_THREAD`]
254///
255pub fn FRENewObjectFromBool(value: FREBoolean, object: *mut FREObject) -> FREResult;
256
257/// Retrieves a string representation of the object referred to by
258/// the given object. The referenced string is immutable and valid
259/// only for duration of the call to a registered function. If the
260/// caller wishes to keep the string, they must keep a copy of it.
261///
262/// # Parameters
263///
264/// - `object`: The string to be retrieved.
265/// - `length`: The size, in bytes, of the string. Includes the NUL terminator.
266/// # 😡👆
267/// IT DOES NOT INCLUDE THE NUL TERMINATOR IN PRACTICE (AIR-SDK-51.1.3.1).
268///
269/// - `value`: A pointer to a possibly temporary copy of the string.
270///
271/// # Returns
272///
273/// - [`FREResult::FRE_OK`]
274/// - [`FREResult::FRE_TYPE_MISMATCH`]
275/// - [`FREResult::FRE_INVALID_OBJECT`]
276/// - [`FREResult::FRE_INVALID_ARGUMENT`]
277/// - [`FREResult::FRE_WRONG_THREAD`]
278///
279pub fn FREGetObjectAsUTF8(object: FREObject, length: *mut uint32_t, value: *mut FREStr) -> FREResult;
280
281/// Creates a new `String` object that contains a copy of the specified string.
282///
283/// # Parameters
284///
285/// - `length`: The length, in bytes, of the original string. Must include the NUL terminator.
286/// # 😡👆
287/// IT DOES NOT INCLUDE THE NUL TERMINATOR IN PRACTICE.
288///
289/// - `value`: A pointer to the original string.
290/// - `object`: Receives a reference to the new string object.
291///
292/// # Returns
293///
294/// - [`FREResult::FRE_OK`]
295/// - [`FREResult::FRE_INVALID_ARGUMENT`]
296/// - [`FREResult::FRE_WRONG_THREAD`]
297///
298pub fn FRENewObjectFromUTF8(length: uint32_t, value: FREStr, object: *mut FREObject) -> FREResult;
299
300
301// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Utility methods ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
302// ╿ ╿
303/// Outputs a trace to the AS3 debugger.
304///
305/// # Parameters
306///
307/// - `strTrace`: A NUL-terminated string to output to the debugger.
308///
309/// # Returns
310///
311/// - [`FREResult::FRE_OK`]
312/// - [`FREResult::FRE_INVALID_ARGUMENT`] If `strTrace` is null.
313/// - [`FREResult::FRE_WRONG_THREAD`]
314///
315pub fn FRETrace(ctx: FREContext, strTrace: FREStr) -> FREResult;
316}
317
318/// Declared as [`uint8_t`] instead of the C enum storage type,
319/// because the runtime writes only one byte in practice.
320///
321#[derive(Debug, Clone, Copy, PartialEq, Eq)]
322#[repr(transparent)]
323pub struct FRERenderMode(uint8_t);
324impl FRERenderMode {
325 pub const FRE_RENDERMODE_UNKNOWN: Self = Self(0);
326 pub const FRE_RENDERMODE_NONE: Self = Self(1);
327 pub const FRE_RENDERMODE_CPU: Self = Self(2);
328 pub const FRE_RENDERMODE_DIRECT_OGLES: Self = Self(3);
329 pub const FRE_RENDERMODE_DIRECT_OGL: Self = Self(4);
330 pub const FRE_RENDERMODE_DIRECT_D3D9: Self = Self(5);
331 pub const FRE_RENDERMODE_DIRECT_D3D10: Self = Self(6);
332 pub const FRE_RENDERMODE_DIRECT_D3D11: Self = Self(7);
333 pub const FRE_RENDERMODE_SOFTWARE_GDI: Self = Self(8);
334 pub const FRE_RENDERMODE_GPU_OGLES: Self = Self(9);
335 pub fn as_i32(self) -> i32 {self.0 as i32}
336 pub fn as_u32(self) -> u32 {self.0 as u32}
337}
338impl std::fmt::Display for FRERenderMode {fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {write!(f, "{:#010X}", self.as_u32())}}
339
340unsafe extern "C" {
341/// Returns the current render mode and mechanism for AIR
342///
343/// # Parameters
344///
345/// - `stage`: The AS3 `Stage` object for which to return the render mode.
346/// If this parameter is passed as null, the function will use the main/initial stage.
347/// - `pRenderMode`: A pointer to a byte that will be populated with one
348/// of the render modes from the [`FRERenderMode`] enumeration.
349///
350/// # Returns
351///
352/// - [`FREResult::FRE_OK`]
353/// - [`FREResult::FRE_INVALID_ARGUMENT`] If `pRenderMode` is null.
354/// - [`FREResult::FRE_INVALID_OBJECT`] If `stage` is non-null but not a `Stage` object.
355/// - [`FREResult::FRE_WRONG_THREAD`]
356///
357pub fn FREGetRenderMode(ctx: FREContext, stage: FREObject, pRenderMode: *mut FRERenderMode) -> FREResult;
358
359/// Sets a `MediaBuffer` object as the rendering source for a `DisplayObject`.
360///
361/// # Parameters
362///
363/// - `source`: The AS3 `MediaBuffer` object that will be used to render into the display object.
364/// - `target`: The AS3 `DisplayObject` object that will render the contents from the `MediaBuffer`.
365///
366/// # Returns
367///
368/// - [`FREResult::FRE_OK`]
369/// - [`FREResult::FRE_INVALID_ARGUMENT`] If either argument is null.
370/// - [`FREResult::FRE_INVALID_OBJECT`] If the objects are incorrect types.
371/// - [`FREResult::FRE_WRONG_THREAD`]
372///
373pub fn FRESetRenderSource(ctx: FREContext, source: FREObject, target: FREObject) -> FREResult;
374
375/// Locks a `MediaBuffer` bitmap and returns information about the data storage.
376///
377/// Note that for every call to [`FREMediaBufferLock`], a corresponding call to [`FREMediaBufferUnlock`] must be made.
378/// Ideally this would be as swift as possible, as locking a media buffer would impact rendering of any bitmap
379/// it contains. The unlock must be called prior to returning from the ANE function call though.
380///
381/// # Parameters
382///
383/// - `ctx`: The [`FREContext`] for the native extension instance.
384/// - `mediaBuffer`: The AS3 `MediaBuffer` object for which the image data is requested.
385/// - `pData`: Pointer to a byte pointer that will be set to the internal image data.
386/// - `pWidth`: Pointer to a value that will be set to the width of the image data.
387/// - `pHeight`: Pointer to a value that will be set to the height of the image data.
388/// - `pStride`: Pointer to a value that will be set to the stride i.e. number of bytes between the start of each row on the image.
389/// - `pFormat`: Pointer to a value that will be set to a format value (for future usage: currently images are ARGB format).
390///
391/// # Returns
392///
393/// - [`FREResult::FRE_OK`]
394/// - [`FREResult::FRE_INVALID_ARGUMENT`] If any parameter is null.
395/// - [`FREResult::FRE_INVALID_OBJECT`] If the `MediaBuffer` object has an incorrect type.
396/// - [`FREResult::FRE_WRONG_THREAD`] If called from the wrong thread; at some point this function will be updated to allow multi-thread calling.
397///
398pub fn FREMediaBufferLock (
399 ctx: FREContext,
400 mediaBuffer: FREObject,
401 pData: *mut FREBytes,
402 pWidth: *mut uint32_t,
403 pHeight: *mut uint32_t,
404 pStride: *mut uint32_t,
405 pFormat: *mut uint32_t,
406) -> FREResult;
407
408/// Unlocks a `MediaBuffer` bitmap.
409///
410/// Currently the `bUpdate` parameter is ignored: changes to the data provided by the [`FREMediaBufferLock`] function will
411/// always have an impact on the rendered bitmap. This parameter is provided to allow for future flexibility.
412///
413/// # Parameters
414///
415/// - `ctx`: The [`FREContext`] for the native extension instance.
416/// - `mediaBuffer`: The AS3 `MediaBuffer` object for which the image data is released.
417/// - `bUpdate`: Whether to use the updated data for rendering. Note that this parameter may not have any effect.
418///
419/// # Returns
420///
421/// - [`FREResult::FRE_OK`]
422/// - [`FREResult::FRE_INVALID_ARGUMENT`] If the `ctx` or `mediaBuffer` parameter is null.
423/// - [`FREResult::FRE_INVALID_OBJECT`] If the `MediaBuffer` object has an incorrect type.
424/// - [`FREResult::FRE_WRONG_THREAD`] If called from the wrong thread; at some point this function will be updated to allow multi-thread calling.
425///
426pub fn FREMediaBufferUnlock(ctx: FREContext, mediaBuffer: FREObject, bUpdate: uint32_t) -> FREResult;
427
428
429// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Object Access ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
430// ╿ ╿
431/// # Parameters
432///
433/// - `className`: UTF-8 encoded name of the class being constructed.
434/// - `thrownException`: A pointer to a handle that can receive the handle of any AS3 `Error` thrown during execution.
435/// May be null if the caller does not want to receive this handle.
436/// If not null and no error occurs, it is set to an invalid handle value.
437///
438/// # Returns
439///
440/// - [`FREResult::FRE_OK`]
441/// - [`FREResult::FRE_TYPE_MISMATCH`]
442/// - [`FREResult::FRE_INVALID_OBJECT`]
443/// - [`FREResult::FRE_INVALID_ARGUMENT`]
444/// - [`FREResult::FRE_ACTIONSCRIPT_ERROR`] If an AS3 exception results from calling this method.
445/// In this case, `thrownException` will be set to the handle of the thrown value.
446/// - [`FREResult::FRE_ILLEGAL_STATE`] If a `ByteArray` or `BitmapData` has been acquired and not yet released.
447/// - [`FREResult::FRE_NO_SUCH_NAME`]
448/// - [`FREResult::FRE_WRONG_THREAD`]
449///
450pub fn FRENewObject (
451 className: FREStr,
452 argc: uint32_t,
453 argv: *mut FREObject,
454 object: *mut FREObject,
455 thrownException: *mut FREObject,
456) -> FREResult;
457
458/// # Parameters
459///
460/// - `propertyName`: UTF-8 encoded name of the property being fetched.
461/// - `thrownException`: A pointer to a handle that can receive the handle of any AS3 `Error` thrown during getting the property.
462/// May be null if the caller does not want to receive this handle.
463/// If not null and no error occurs, it is set to an invalid handle value.
464///
465/// # Returns
466///
467/// - [`FREResult::FRE_OK`]
468/// - [`FREResult::FRE_TYPE_MISMATCH`]
469/// - [`FREResult::FRE_INVALID_OBJECT`]
470/// - [`FREResult::FRE_INVALID_ARGUMENT`]
471/// - [`FREResult::FRE_ACTIONSCRIPT_ERROR`] If an AS3 exception results from getting this property.
472/// In this case, `thrownException` will be set to the handle of the thrown value.
473/// - [`FREResult::FRE_NO_SUCH_NAME`] If the named property doesn't exist,
474/// or if the reference is ambiguous because the property exists in more than one namespace.
475/// - [`FREResult::FRE_ILLEGAL_STATE`] If a `ByteArray` or `BitmapData` has been acquired and not yet released.
476/// - [`FREResult::FRE_WRONG_THREAD`]
477///
478pub fn FREGetObjectProperty (
479 object: FREObject,
480 propertyName: FREStr,
481 propertyValue: *mut FREObject,
482 thrownException: *mut FREObject,
483) -> FREResult;
484
485
486/// # Parameters
487///
488/// - `propertyName`: UTF-8 encoded name of the property being set.
489/// - `thrownException`: A pointer to a handle that can receive the handle of any AS3 `Error` thrown during method execution.
490/// May be null if the caller does not want to receive this handle.
491/// If not null and no error occurs, it is set to an invalid handle value.
492///
493/// # Returns
494///
495/// - [`FREResult::FRE_OK`]
496/// - [`FREResult::FRE_TYPE_MISMATCH`]
497/// - [`FREResult::FRE_INVALID_OBJECT`]
498/// - [`FREResult::FRE_INVALID_ARGUMENT`]
499/// - [`FREResult::FRE_ACTIONSCRIPT_ERROR`] If an AS3 exception results from getting this property.
500/// In this case, `thrownException` will be set to the handle of the thrown value.
501/// - [`FREResult::FRE_NO_SUCH_NAME`] If the named property doesn't exist,
502/// or if the reference is ambiguous because the property exists in more than one namespace.
503/// - [`FREResult::FRE_ILLEGAL_STATE`] If a `ByteArray` or `BitmapData` has been acquired and not yet released.
504/// - [`FREResult::FRE_READ_ONLY`]
505/// - [`FREResult::FRE_WRONG_THREAD`]
506///
507pub fn FRESetObjectProperty (
508 object: FREObject,
509 propertyName: FREStr,
510 propertyValue: FREObject,
511 thrownException: *mut FREObject,
512) -> FREResult;
513
514/// # Parameters
515///
516/// - `methodName`: UTF-8 encoded NUL-terminated name of the method being invoked.
517/// - `thrownException`: A pointer to a handle that can receive the handle of any AS3 `Error` thrown during method execution.
518/// May be null if the caller does not want to receive this handle.
519/// If not null and no error occurs, it is set to an invalid handle value.
520///
521/// # Returns
522///
523/// - [`FREResult::FRE_OK`]
524/// - [`FREResult::FRE_TYPE_MISMATCH`]
525/// - [`FREResult::FRE_INVALID_OBJECT`]
526/// - [`FREResult::FRE_INVALID_ARGUMENT`]
527/// - [`FREResult::FRE_ACTIONSCRIPT_ERROR`] If an AS3 exception results from calling this method.
528/// In this case, `thrownException` will be set to the handle of the thrown value.
529/// - [`FREResult::FRE_NO_SUCH_NAME`] If the named method doesn't exist,
530/// or if the reference is ambiguous because the method exists in more than one namespace.
531/// - [`FREResult::FRE_ILLEGAL_STATE`] If a `ByteArray` or `BitmapData` has been acquired and not yet released.
532/// - [`FREResult::FRE_WRONG_THREAD`]
533///
534pub fn FRECallObjectMethod (
535 object: FREObject,
536 methodName: FREStr,
537 argc: uint32_t,
538 argv: *mut FREObject,
539 result: *mut FREObject,
540 thrownException: *mut FREObject,
541) -> FREResult;
542}
543
544
545// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ BitmapData Access ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
546// ╿ ╿
547/// A non-owning descriptor for bitmap data.
548///
549#[derive(Debug)]
550#[repr(C)]
551pub struct FREBitmapData {
552
553 /// Width of the `BitmapData` bitmap.
554 ///
555 pub width: uint32_t,
556
557 /// Height of the `BitmapData` bitmap.
558 ///
559 pub height: uint32_t,
560
561 /// If non-zero, pixel format is ARGB32, otherwise pixel format is _RGB32, host endianness.
562 ///
563 pub hasAlpha: FREBoolean,
564
565 /// Pixel color values are premultiplied with alpha if non-zero, un-multiplied if zero.
566 ///
567 pub isPremultiplied: FREBoolean,
568
569 /// Line stride in number of 32 bit values, typically the same as `width`.
570 ///
571 pub lineStride32: uint32_t,
572
573 /// Pointer to the first 32-bit pixel of the bitmap data.
574 ///
575 pub bits32: *mut uint32_t,
576}
577
578/// A non-owning descriptor for bitmap data.
579///
580#[derive(Debug)]
581#[repr(C)]
582pub struct FREBitmapData2 {
583
584 /// Width of the `BitmapData` bitmap.
585 ///
586 pub width: uint32_t,
587
588 /// Height of the `BitmapData` bitmap.
589 ///
590 pub height: uint32_t,
591
592 /// If non-zero, pixel format is ARGB32, otherwise pixel format is _RGB32, host endianness.
593 ///
594 pub hasAlpha: FREBoolean,
595
596 /// Pixel color values are premultiplied with alpha if non-zero, un-multiplied if zero.
597 ///
598 pub isPremultiplied: FREBoolean,
599
600 /// Line stride in number of 32 bit values, typically the same as `width`.
601 ///
602 pub lineStride32: uint32_t,
603
604 /// If non-zero, last row of pixels starts at bits32, otherwise, first row of pixels starts at bits32.
605 ///
606 pub isInvertedY: FREBoolean,
607
608 /// Pointer to the first 32-bit pixel of the bitmap data.
609 ///
610 pub bits32: *mut uint32_t,
611}
612
613unsafe extern "C" {
614/// Referenced data is valid only for duration of the call to a registered function.
615///
616/// # Returns
617///
618/// - [`FREResult::FRE_OK`]
619/// - [`FREResult::FRE_TYPE_MISMATCH`]
620/// - [`FREResult::FRE_INVALID_OBJECT`]
621/// - [`FREResult::FRE_INVALID_ARGUMENT`]
622/// - [`FREResult::FRE_WRONG_THREAD`]
623/// - [`FREResult::FRE_ILLEGAL_STATE`]
624///
625pub fn FREAcquireBitmapData(object: FREObject, descriptorToSet: *mut FREBitmapData) -> FREResult;
626
627/// Referenced data is valid only for duration of the call to a registered function.
628///
629/// Use of this API requires that the extension and application must be packaged for
630/// the 3.1 namespace or later.
631///
632/// # Returns
633///
634/// - [`FREResult::FRE_OK`]
635/// - [`FREResult::FRE_TYPE_MISMATCH`]
636/// - [`FREResult::FRE_INVALID_OBJECT`]
637/// - [`FREResult::FRE_INVALID_ARGUMENT`]
638/// - [`FREResult::FRE_WRONG_THREAD`]
639/// - [`FREResult::FRE_ILLEGAL_STATE`]
640///
641pub fn FREAcquireBitmapData2(object: FREObject, descriptorToSet: *mut FREBitmapData2) -> FREResult;
642
643/// `BitmapData` must be acquired to call this. Clients must invalidate any region
644/// they modify in order to notify AIR of the changes. Only invalidated regions are redrawn.
645///
646/// # Returns
647///
648/// - [`FREResult::FRE_OK`]
649/// - [`FREResult::FRE_INVALID_OBJECT`]
650/// - [`FREResult::FRE_WRONG_THREAD`]
651/// - [`FREResult::FRE_ILLEGAL_STATE`]
652/// - [`FREResult::FRE_TYPE_MISMATCH`]
653///
654pub fn FREInvalidateBitmapDataRect (
655 object: FREObject,
656 x: uint32_t,
657 y: uint32_t,
658 width: uint32_t,
659 height: uint32_t,
660) -> FREResult;
661
662/// Release data that has been acquired with an earlier call to [`FREAcquireBitmapData`] or [`FREAcquireBitmapData2`]
663///
664/// # Returns
665///
666/// - [`FREResult::FRE_OK`]
667/// - [`FREResult::FRE_WRONG_THREAD`]
668/// - [`FREResult::FRE_ILLEGAL_STATE`]
669/// - [`FREResult::FRE_TYPE_MISMATCH`]
670///
671pub fn FREReleaseBitmapData(object: FREObject) -> FREResult;
672}
673
674
675// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ByteArray Access ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
676// ╿ ╿
677/// A non-owning descriptor for bytes.
678///
679#[derive(Debug)]
680#[repr(C)]
681pub struct FREByteArray {
682 pub length: uint32_t,
683 pub bytes: FREBytes,
684}
685
686unsafe extern "C" {
687/// Creates a new byte array using optional input information (`length` and optional `byte`)
688///
689/// # Returns
690///
691/// - [`FREResult::FRE_OK`]
692/// - [`FREResult::FRE_INVALID_ARGUMENT`]
693/// - [`FREResult::FRE_WRONG_THREAD`]
694/// - [`FREResult::FRE_ILLEGAL_STATE`]
695///
696pub fn FRENewByteArray(byteArrayData: *mut FREByteArray, handle: *mut FREObject) -> FREResult;
697
698/// Referenced data is valid only for duration of the call to a registered function.
699///
700/// # Returns
701///
702/// - [`FREResult::FRE_OK`]
703/// - [`FREResult::FRE_TYPE_MISMATCH`]
704/// - [`FREResult::FRE_INVALID_OBJECT`]
705/// - [`FREResult::FRE_INVALID_ARGUMENT`]
706/// - [`FREResult::FRE_WRONG_THREAD`]
707/// - [`FREResult::FRE_ILLEGAL_STATE`]
708///
709pub fn FREAcquireByteArray(object: FREObject, byteArrayToSet: *mut FREByteArray) -> FREResult;
710
711/// # Returns
712///
713/// - [`FREResult::FRE_OK`]
714/// - [`FREResult::FRE_INVALID_OBJECT`]
715/// - [`FREResult::FRE_ILLEGAL_STATE`]
716/// - [`FREResult::FRE_WRONG_THREAD`]
717///
718pub fn FREReleaseByteArray(object: FREObject) -> FREResult;
719
720
721// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Array and Vector Access ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
722// ╿ ╿
723/// # Returns
724///
725/// - [`FREResult::FRE_OK`]
726/// - [`FREResult::FRE_INVALID_OBJECT`]
727/// - [`FREResult::FRE_INVALID_ARGUMENT`]
728/// - [`FREResult::FRE_ILLEGAL_STATE`]
729/// - [`FREResult::FRE_TYPE_MISMATCH`]
730/// - [`FREResult::FRE_WRONG_THREAD`]
731///
732pub fn FREGetArrayLength(arrayOrVector: FREObject, length: *mut uint32_t) -> FREResult;
733
734/// # Returns
735///
736/// - [`FREResult::FRE_OK`]
737/// - [`FREResult::FRE_INVALID_OBJECT`]
738/// - [`FREResult::FRE_TYPE_MISMATCH`]
739/// - [`FREResult::FRE_ILLEGAL_STATE`]
740/// - [`FREResult::FRE_INVALID_ARGUMENT`] If `length` is greater than 2^32.
741/// # 🤔👆
742/// THIS DOES NOT MAKE SENSE for a [`uint32_t`] parameter.
743/// Presumably the actual limit is lower, and values near [`uint32_t::MAX`] may fail or crash.
744///
745/// - [`FREResult::FRE_READ_ONLY`] If the handle refers to a `Vector` of fixed size.
746/// - [`FREResult::FRE_WRONG_THREAD`]
747/// - [`FREResult::FRE_INSUFFICIENT_MEMORY`]
748///
749pub fn FRESetArrayLength(arrayOrVector: FREObject, length: uint32_t) -> FREResult;
750
751/// If an `Array` is sparse and an element that isn't defined is requested,
752/// the return value will be [`FREResult::FRE_OK`] but the handle value will be invalid.
753///
754/// # Returns
755///
756/// - [`FREResult::FRE_OK`]
757/// - [`FREResult::FRE_ILLEGAL_STATE`]
758/// - [`FREResult::FRE_INVALID_ARGUMENT`] If the handle refers to a vector
759/// and the index is greater than the size of the array.
760/// - [`FREResult::FRE_INVALID_OBJECT`]
761/// - [`FREResult::FRE_TYPE_MISMATCH`]
762/// - [`FREResult::FRE_WRONG_THREAD`]
763///
764pub fn FREGetArrayElementAt(arrayOrVector: FREObject, index: uint32_t, value: *mut FREObject) -> FREResult;
765
766/// # Returns
767///
768/// - [`FREResult::FRE_OK`]
769/// - [`FREResult::FRE_INVALID_OBJECT`]
770/// - [`FREResult::FRE_ILLEGAL_STATE`]
771/// - [`FREResult::FRE_TYPE_MISMATCH`] If an attempt is made to set a value in a `Vector`
772/// when the type of the value doesn't match the `Vector`'s item type.
773/// - [`FREResult::FRE_WRONG_THREAD`]
774///
775pub fn FRESetArrayElementAt(arrayOrVector: FREObject, index: uint32_t, value: FREObject) -> FREResult;
776
777
778// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ NativeWindow Access ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
779// ╿ ╿
780/// Referenced handle is valid only for duration of the call to a registered function.
781///
782/// # Returns
783///
784/// - [`FREResult::FRE_OK`]
785/// - [`FREResult::FRE_TYPE_MISMATCH`]
786/// - [`FREResult::FRE_INVALID_OBJECT`]
787/// - [`FREResult::FRE_INVALID_ARGUMENT`]
788/// - [`FREResult::FRE_WRONG_THREAD`]
789/// - [`FREResult::FRE_ILLEGAL_STATE`]
790///
791pub fn FREAcquireNativeWindowHandle(nativeWindow: FREObject, handle: *mut FRENativeWindow) -> FREResult;
792
793/// # Returns
794///
795/// - [`FREResult::FRE_OK`]
796/// - [`FREResult::FRE_INVALID_OBJECT`]
797/// - [`FREResult::FRE_ILLEGAL_STATE`]
798/// - [`FREResult::FRE_WRONG_THREAD`]
799///
800pub fn FREReleaseNativeWindowHandle(nativeWindow: FREObject) -> FREResult;
801
802/// Access the native context type for a `Context3D` object. The type depends on the
803/// render mode: currently this is only valid for OpenGL ES rendering and will return
804/// an `EGLContext` object. This object should be valid until the `Context3D` object is
805/// disposed, or the device/application loses the graphics context.
806///
807/// # Example usage in C
808///
809/// ```c
810/// EGLContext airContext = EGL_NO_CONTEXT;
811/// if ( (FRE_OK == FREGetNativeContext3DHandle(args[0], (void**)&airContext)) && (airContext != EGL_NO_CONTEXT) )
812/// // ... do something with the handle ...
813/// ```
814///
815/// # Returns
816///
817/// - [`FREResult::FRE_OK`]
818/// - [`FREResult::FRE_TYPE_MISMATCH`]
819/// - [`FREResult::FRE_INVALID_OBJECT`]
820/// - [`FREResult::FRE_INVALID_ARGUMENT`]
821/// - [`FREResult::FRE_WRONG_THREAD`]
822/// - [`FREResult::FRE_ILLEGAL_STATE`]
823///
824pub fn FREGetNativeContext3DHandle(context3D: FREObject, handle: *mut FREHandle) -> FREResult;
825
826
827// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Extension Context Access ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
828// ╿ ╿
829/// Get the [`FREContext`] object associated with any `ExtensionContext` object. Note that
830/// the [`FREContext`] object may become invalid based on what happens with the other `ExtensionContext`,
831/// so this value should not be cached between function calls.
832///
833/// # Parameters
834///
835/// - `objExtensionContext`: The `ExtensionContext` (AS3 object) for which the [`FREContext`] handle is required.
836/// - `pContext`: The [`FREContext`] (C handle) associated with the given `ExtensionContext`.
837///
838/// # Returns
839///
840/// - [`FREResult::FRE_OK`]
841/// - [`FREResult::FRE_TYPE_MISMATCH`]
842/// - [`FREResult::FRE_INVALID_OBJECT`]
843/// - [`FREResult::FRE_INVALID_ARGUMENT`]
844/// - [`FREResult::FRE_WRONG_THREAD`]
845/// - [`FREResult::FRE_ILLEGAL_STATE`]
846///
847pub fn FREGetFREContextFromExtensionContext(objExtensionContext: FREObject, pContext: *mut FREContext) -> FREResult;
848
849
850// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Callbacks ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
851// ╿ ╿
852/// Causes a `StatusEvent` to be dispatched from the associated `ExtensionContext` object.
853///
854/// Dispatch happens asynchronously, even if this is called during a call to a registered function.
855///
856/// The AS3 portion of this extension can listen for that event and,
857/// upon receipt, query the native portion for details of the event that occurred.
858///
859/// This call is thread-safe and may be invoked from any thread. The string
860/// values are copied before the call returns.
861///
862/// # Returns
863///
864/// - [`FREResult::FRE_OK`] In all circumstances,
865/// as the referenced object cannot necessarily be checked for validity on the invoking thread.
866/// However, no event will be dispatched if the object is invalid or not an `EventDispatcher`.
867/// - [`FREResult::FRE_INVALID_ARGUMENT`] If `code` or `level` is null.
868///
869pub fn FREDispatchStatusEventAsync(ctx: FREContext, code: FREStr, level: FREStr) -> FREResult;
870}
871