灵动游戏研究室

文档-资料-开源

Flash-Alchemy-API

1. 介绍

Alchemy是一个通过LLVMC/C++源代码编译成Flash虚拟机目标代码的技术,它提供了一个编译器,用于编译C/C++源码和相关工具,并提供了一套ASC/C++代码交互的API。本文介绍的是提供给C/C++API,API定义在AS3.h头文件中

C-API

2. 对象管理

2.1. AS3_VAL

用来保存AS对象的类型,头文件中的定义typedef struct _AS3_Val *AS3_Val;

2.2. void  AS3_Acquire(AS3_Val obj)

用来增加obj的引用计数,关系到对象在虚拟机中的回收

2.3. void AS3_Release(AS3_Val obj)

用来减少obj的引用计数,关系到对象在虚拟机中的回收

2.4. AS3_Val AS3_New(AS3_Val constr, AS3_Val params)

用来构建一个新的AS对象,

Constr一个AS对象的构造方法,可以通过AS3_NSGet方法获取

Params构造方法的参数,一个AS数组,数组可以空,但不能为NULL

2.5. AS3_Malloced_Str AS3_TypeOf(AS3_Val obj)

获取objAS类型名称,返回一个堆中的字符串所以字符串必须释放

AS3_Malloced_Str在头文件中的定义typedef char *AS3_Malloced_Str;

2.6. int AS3_InstanceOf(AS3_Val val, AS3_Val type)

判断val对象是否是指定type类型

val一个AS对象

type一个使用NSGet获取的对象

返回0表示不是指定类型,返回非零则是

例子:

AS3_Val arrClass =AS3_NSGetS(NULL,”Array”);

if(!AS3_InstanceOf(AS3_Array(“”), arrClass ))) sztrace(“whaaa!”);

AS3_Release(arrClass);

2.7. AS3_Val AS3_NSGet(AS3_Val ns, AS3_Val prop)

该方法从指定的命名空间下获取一个对应名称的属性

ns一个包含命名空间的AS字符串,NULL的时候表示默认空间(trace或者Array就在这个空间)

prop包含你要获取的属性的名称的AS字符串

函数返回指定的属性,一般情况是个函数。没有找到返回NULL

例子:

AS3_Val flash_utils_namespace = AS3_String(“flash.utils”);

AS3_Val ByteArray_property = AS3_String(“ByteArray”);

AS3_Val ByteArray_class = AS3_NSGetS(flash_utils_namespace, ByteArray_property);

AS3_Val byteArray = AS3_New(ByteArray_class, no_params);

AS3_Release(ByteArray_class);

AS3_Release(ByteArray_property);

AS3_Release(flash_utils_namespace);

2.8. AS3_Val AS3_NSGetS(AS3_Val ns, const char *prop)

AS3_Val AS3_NSGet函数基本一致,只是第二个参数为一个C字符串

例子:

AS3_Val flash_utils_namespace = AS3_String(“flash.utils”);

AS3_Val ByteArray_class = AS3_NSGetS(flash_utils_namespace, ”ByteArray”);

AS3_Val byteArray = AS3_New(ByteArray_class, no_params);

AS3_Release(ByteArray_class);

AS3_Release(flash_utils_namespace);

3. C/C++的对象转换到AS

3.1. AS3_Val AS3_String(const char* str)

使用一个C字符串构造的AS字符串(\0结束),必须使用AS3_Release()释放

3.2. AS3_Val AS3_StringN(const char* str, int len)

使用一个C字符串构造并指定长度(只获取指定长度),必须使用AS3_Release()释放

3.3. AS3_Val AS3_Int(int)

构造一个ASint对象,必须使用AS3_Release()释放

3.4. AS3_Val AS3_Ptr(void* ptr)

Returns a newly created ActionScript uint whose value is the offset of this value from the beginning of the ByteArray being used as ”ram”. Must be released with AS3_Release().

3.5. AS3_Val AS3_Number(double d)

构造一个ASNumber对象,必须使用AS3_Release()释放

3.6. AS3_Val AS3_True()

顾名思义,必须使用AS3_Release()释放

3.7. AS3_Val AS3_False()

顾名思义,必须使用AS3_Release()释放

3.8. AS3_Val AS3_Null()

返回一个ASnull引用,这个不需要释放

3.9. AS3_Val AS3_Undefined()

返回一个ASundefined引用,这个不需要释放

3.10. AS3_Val AS3_Array(const char *tt, …)

返回一个AS的数组,第一个参数tt是一个类型列表如“type0,type1″,tt支持以下值

IntType – maps to int

PtrType – maps to void*

DoubleType – maps to double

StrType – maps to char*

AS3ValType – maps to AS3_Val

必须使用AS3_Release()释放

例子:

AS3_Val point = AS3_Array(“IntType, IntType”, x, y);

3.11. AS3_Val AS3_Object(const char *tt, …)

基本同数组的写法一致,tt的写法不同

例子:

AS3_Val addr = AS3_Array(“city:StrType, state:StrType, zip:StrType”, ”Anytown”, ”State”, ”12345″);

4. AS对象转换到C/C++

4.1. AS3_Malloced_Str AS3_StringValue(AS3_Val obj)

AS对象转换成一个字符串,字符串必须释放

4.2. int AS3_IntValue(AS3_Val obj)

AS对象转换成一个int

4.3. void* AS3_PtrValue(AS3_Val obj)

AS对象转换成一个指针

4.4. double AS3_NumberValue(AS3_Val obj)

AS对象转换成double

4.5. void AS3_ArrayValue(AS3_Val arr, const char *tt, …)

AS的数组对象中获取数据,体现的很明显

例子:

int arg0 = 0;

char* arg1 = NULL;

double arg2 = 0.0;

AS3_ArrayValue(arr, ”IntType, StrType, DoubleType”, &arg0, &arg1, &arg2);

4.6. void AS3_ObjectValue(AS3_Val arr, const char *tt, …)

ASObject对象中获取数据,例子体现的很明显

例子:

int arg0 = 0;

char* arg1 = NULL;

double arg2 = 0.0;

AS3_ObjectValue(obj, ”foo:IntType, bar:StrType, baz:DoubleType”, &arg0, &arg1, &arg2);

5. C/C++中调用AS的函数

5.1. AS3_Val AS3_Get(AS3_Val obj, AS3_Val prop)

该方法允许程序用一个AS对象身上获取指定名称的属性

obj一个AS对象

prop一个包含属性名称的AS字符串

函数返回getter方法(属性包含gettersetter两个方法),如果没有找到,返回NULL

例子:

AS3_Val length_property = AS3_String(“length”);

AS3_Val length = AS3_Get(byteArray, length_property);

AS3_Release(length_property);

5.2. AS3_Val AS3_GetS(AS3_Val obj, const char *prop)

AS3_GET函数基本一致,第二个参数换成了字符串

例子:

AS3_Val length = AS3_GetS(byteArray, ”length”);

5.3. AS3_Val AS3_Set(AS3_Val obj, AS3_Val prop, AS3_Val val)

obj中指定名称prop的属性赋值为val,无返回值

例子:

AS3_Val position_property = AS3_String(“position”);

AS3_Val zero = AS3_Int(0);

AS3_SetS(byteArray, position_property, zero);

AS3_Release(zero);

AS3_Release(position_property);

5.4. AS3_Val AS3_SetS(AS3_Val obj, const char *prop, AS3_Val val)

AS3_Set()基本一致,第二个参数换成C字符串

例子:

AS3_Val zero = AS3_Int(0);

AS3_SetS(byteArray, ”position”, zero);

AS3_Release(zero);

5.5. AS3_Val AS3_Call(AS3_Val func, AS3_Val thiz, AS3_Val params)

调用thiz对象的func方法,并传递params参数

func一个使用NSGet/NSGetS或者一个对象使用Get/GetS获得的方法引用

thiz一个包含func方法的可用对象,也可以使用AS3_Undefined()来调用顶级函数,trace

params一个ASArray对象,包含函数需要的参数

例子:

AS3_Val baNS = AS3_String(“flash.utils”);

AS3_Val baClass = AS3_NSGetS(baNS, ”ByteArray”);

AS3_Val emptyParams = AS3_Array(“”);

AS3_Val ba = AS3_New(baClass, emptyParams);

AS3_Val readUTFBytes = AS3_GetS(ba, ”readUTFBytes”);

AS3_Val lenParams = AS3_Array(“IntType”, strlen(buf));

AS3_Val str = AS3_Call(readUTFBytes, ba, lenParams);

5.6. AS3_Val AS3_CallS(const char *func, AS3_Val thiz, AS3_Val params)

AS3_Call基本一致,第一个参数换成了C字符串

例子:

AS3_Val str = AS3_Call(“readUTFBytes”, ba, lenParams);

5.7. AS3_Val AS3_CallT(AS3_Val func, AS3_Val thiz, const char *tt, …)

AS3_Call基本一致,最后的参数换成了构造AS3_ArrayValue的参数

5.8. AS3_Val AS3_CallTS(const char *func, AS3_Val thiz, const char *tt, …)

AS3_Call基本一致,第一个参数换成C字符串,后面换成构造AS3_ArrayValue的参数

5.9. void *AS3_Shim(AS3_Val func, AS3_Val thiz, const char *rt, const char *tt, int varargs)

thiz.func(…)转换成一个指向函数的C指针

例子:

int (*myfunc)(const char *s, double n) = AS3_Shim(someFunc, someThiz, ”IntType, StrType, NumberType”, false);

5.10. AS3_Val AS3_Proxy()

Create a Proxy object that delegates callProperty, etc. to the Function vars in the object in the flash_delegate namespace!

i.e., delgates to flash_delegate::callProperty, not public callProperty.

6. AS调用C/C++的函数

6.1. AS3_ThunkProc

用来表示一个回调函数

typedef AS3_Val (*AS3_ThunkProc)(void *data, AS3_Val params);

6.2. AS3_Val AS3_Function(void *data, AS3_ThunkProc proc)

创建一个同步的回调函数对象

data能够用来保存函数的状态

6.3. AS3_Val AS3_FunctionAsync(void *data, AS3_ThunkProc proc)

创建一个异步的回调函数对象

data能够用来保存函数的状态

6.4. AS3_Val AS3_FunctionT(void *data, void *proc, const char *rt, const char *tt, int varargs)

创建一个同步的回调函数对象

data能够用来保存函数的状态

proc一个回调函数指针

rt返回类型

tt参数类型列表

varargs(文档里面没有具体解释)

6.5. AS3_Val AS3_FunctionAsyncT(void *data, void *proc, const char *rt, const char *tt, int varargs)

创建一个异步的回调函数对象

data能够用来保存函数的状态

proc一个回调函数指针

rt返回类型

tt参数类型列表

varargs(文档里面没有具体解释)

7. 杂项

7.1. void AS3_LibInit(AS3_Val libData)

该方法告知虚拟机你的库已经初始化完毕

libData是一个ASObject对象,包含你的库函数

这个函数不会返回,所以该函数后不需要写代码。如果C里面不调用该函数,虚拟机不会执行任何C以外的代码。Alchemy提供的例子项目AS3Lib有具体的使用样本

7.2. AS3_Val AS3_Stage()

返回虚拟机的stage对象

7.3. AS3_Val AS3_Ram()

该方法返回一个ByteArray,表示C程序使用的所有RAM,谨慎使用

7.4. void flyield()

发起控制权交给flash,并在下一个时间切片获取到控制权继续向下执行

7.5. void sztrace(char* msg)

该方法会把msg输出到trace窗口,或者通过swfbridge输出到stdout

7.6. void AS3_Trace(AS3_Val val)

该方法会把val作为字符串输出到trace窗口,或者通过swfbridge输出到stdout

7.7. int AS3_ByteArray_readBytes(void *dst, AS3_Val src, int len)

ASByteArray对象src上读取长度为len的字节到dst

7.8. int AS3_ByteArray_writeBytes(AS3_Val dst, void *src, int len)

src上写入len和字节到ASByteArray对象dst

7.9. int AS3_ByteArray_seek(AS3_Val dst, int offs, int whence)

按照lseek的规则调整ByteArray对象dst的读写位置

参数offset 为根据参数whence来移动读写位置的位移数。 

whence为下列一种:SEEK_SET,SEEK_CURSEEK_END和依次为012)

SEEK_SET 将读写位置指向文件头后再增加offset个位移量。   

SEEK_CUR 以目前的读写位置往后增加offset个位移量。   

SEEK_END 将读写位置指向文件尾后再增加offset个位移量。   

whence 值为SEEK_CUR SEEK_END时,参数offet允许负值的出现。

当调用成功时则返回目前的读写位置,也就是距离文件开头多少个字节。若有错误则返回-1。 

AS3-API

1. CLibInit

该类用于暴露C程序的功能,它有如下函数

init():*

该函数用来初始化C程序,函数没有参数,返回一个包含C代码输出函数的对象

setSprite(sp:Sprite):void

该函数会将一个sprite对象作为命令行提供给alchemy使用,它会自动创建一个TextField来接受stdoutstderr,同时输入到stdin

putEnv(key:String, value:String):void

允许你设置C中通过getenv()函数获取的环境变量

supplyFile(path:String, data:ByteArray):void

提供一个指定路径的文件给C程序,因为虚拟机中没有给予C程序文件权限

Alchemy的运行情况存储在一个全局变量gstate

2. GLEByteArrayProvider

该类允许你获取一个作为CRAMByteArray

get():ByteArray

返回当前域内存或者分配一个新的,如果不指定将是小头字节

3. MemUser

该类允许你操控C库的RAM,一下函数的addr均表示偏移地址

_mr32(addr:int):int

addr的位置获取一个32int

_mru16(addr:int):int

addr的位置获取一个16位无符号int

_mrs16(addr:int):int

addr的位置获取一个16位有符号int

_mru8(addr:int):int

addr的位置获取一个8位无符号int

_mrs8(addr:int):int

addr的位置获取一个8位有符号int

_mrf(addr:int):Number

addr的位置获取一个float

_mrd(addr:int):Number

addr的位置获取一个double

_mw32(addr:int, val:int):void

addr的位置写入一个32int

_mw16(addr:int, val:int):void

addr的位置写入一个16int

_mw8(addr:int, val:int):void

addr的位置写入一个8int

_mwf(addr:int, val:Number):void

addr的位置写入一个float

_mwd(addr:int, val:Number):void

addr的位置写入一个double

4. Calling Functions Exported from C

想要调用C库中的函数,必须进行一下步骤

① 保证swc已经包含在你的项目中

② importcmodule.<your_lib_name>

③ 创建一个CLibInit对象

④ 调用该对象的init()方法获取并保存返回的Object

⑤ 通过返回的对象调用你输出的函数

例子:

import cmodule.example.CLibInit;

const libInitializer:CLibInit = new CLibInit();

const lib:Object = libInitializer.init();

lib.myExportedFunc(“param1″, 1234);

你可能会在swc中看到很多其他的方法,但是还是必须通过以上方法调用你的库。调用其他上面没有提到的方法都是不被支持的。

 

 

, ,

发表评论