diff --git a/native/cocos/scripting/js-bindings/docs/JSB2.0-learning-zh.md b/native/cocos/scripting/js-bindings/docs/JSB2.0-learning-zh.md index a257d70ebe..95690d6913 100644 --- a/native/cocos/scripting/js-bindings/docs/JSB2.0-learning-zh.md +++ b/native/cocos/scripting/js-bindings/docs/JSB2.0-learning-zh.md @@ -714,7 +714,185 @@ Delegate obj, onCallback: 6, this.myVar: 105 setCallback(nullptr) ``` -### +### 如何使用cocos2d-x bindings这层的类型转换辅助函数? + +类型转换辅助函数位于`cocos/scripting/js-bindings/manual/jsb_conversions.hpp/.cpp`中,其包含: + +#### se::Value转换为C++类型 +``` +bool seval_to_int32(const se::Value& v, int32_t* ret); +bool seval_to_uint32(const se::Value& v, uint32_t* ret); +bool seval_to_int8(const se::Value& v, int8_t* ret); +bool seval_to_uint8(const se::Value& v, uint8_t* ret); +bool seval_to_int16(const se::Value& v, int16_t* ret); +bool seval_to_uint16(const se::Value& v, uint16_t* ret); +bool seval_to_boolean(const se::Value& v, bool* ret); +bool seval_to_float(const se::Value& v, float* ret); +bool seval_to_double(const se::Value& v, double* ret); +bool seval_to_long(const se::Value& v, long* ret); +bool seval_to_ulong(const se::Value& v, unsigned long* ret); +bool seval_to_longlong(const se::Value& v, long long* ret); +bool seval_to_ssize(const se::Value& v, ssize_t* ret); +bool seval_to_std_string(const se::Value& v, std::string* ret); +bool seval_to_Vec2(const se::Value& v, cocos2d::Vec2* pt); +bool seval_to_Vec3(const se::Value& v, cocos2d::Vec3* pt); +bool seval_to_Vec4(const se::Value& v, cocos2d::Vec4* pt); +bool seval_to_Mat4(const se::Value& v, cocos2d::Mat4* mat); +bool seval_to_Size(const se::Value& v, cocos2d::Size* size); +bool seval_to_Rect(const se::Value& v, cocos2d::Rect* rect); +bool seval_to_Color3B(const se::Value& v, cocos2d::Color3B* color); +bool seval_to_Color4B(const se::Value& v, cocos2d::Color4B* color); +bool seval_to_Color4F(const se::Value& v, cocos2d::Color4F* color); +bool seval_to_ccvalue(const se::Value& v, cocos2d::Value* ret); +bool seval_to_ccvaluemap(const se::Value& v, cocos2d::ValueMap* ret); +bool seval_to_ccvaluemapintkey(const se::Value& v, cocos2d::ValueMapIntKey* ret); +bool seval_to_ccvaluevector(const se::Value& v, cocos2d::ValueVector* ret); +bool sevals_variadic_to_ccvaluevector(const se::ValueArray& args, cocos2d::ValueVector* ret); +bool seval_to_blendfunc(const se::Value& v, cocos2d::BlendFunc* ret); +bool seval_to_std_vector_string(const se::Value& v, std::vector* ret); +bool seval_to_std_vector_int(const se::Value& v, std::vector* ret); +bool seval_to_std_vector_float(const se::Value& v, std::vector* ret); +bool seval_to_std_vector_Vec2(const se::Value& v, std::vector* ret); +bool seval_to_std_vector_Touch(const se::Value& v, std::vector* ret); +bool seval_to_std_map_string_string(const se::Value& v, std::map* ret); +bool seval_to_FontDefinition(const se::Value& v, cocos2d::FontDefinition* ret); +bool seval_to_Acceleration(const se::Value& v, cocos2d::Acceleration* ret); +bool seval_to_Quaternion(const se::Value& v, cocos2d::Quaternion* ret); +bool seval_to_AffineTransform(const se::Value& v, cocos2d::AffineTransform* ret); +//bool seval_to_Viewport(const se::Value& v, cocos2d::experimental::Viewport* ret); +bool seval_to_Data(const se::Value& v, cocos2d::Data* ret); +bool seval_to_DownloaderHints(const se::Value& v, cocos2d::network::DownloaderHints* ret); +bool seval_to_TTFConfig(const se::Value& v, cocos2d::TTFConfig* ret); + +//box2d seval to native convertion +bool seval_to_b2Vec2(const se::Value& v, b2Vec2* ret); +bool seval_to_b2AABB(const se::Value& v, b2AABB* ret); + +template +bool seval_to_native_ptr(const se::Value& v, T* ret); + +template +bool seval_to_Vector(const se::Value& v, cocos2d::Vector* ret); + +template +bool seval_to_Map_string_key(const se::Value& v, cocos2d::Map* ret) + +``` + +#### C++类型转换为se::Value + +```c++ +bool int8_to_seval(int8_t v, se::Value* ret); +bool uint8_to_seval(uint8_t v, se::Value* ret); +bool int32_to_seval(int32_t v, se::Value* ret); +bool uint32_to_seval(uint32_t v, se::Value* ret); +bool int16_to_seval(uint16_t v, se::Value* ret); +bool uint16_to_seval(uint16_t v, se::Value* ret); +bool boolean_to_seval(bool v, se::Value* ret); +bool float_to_seval(float v, se::Value* ret); +bool double_to_seval(double v, se::Value* ret); +bool long_to_seval(long v, se::Value* ret); +bool ulong_to_seval(unsigned long v, se::Value* ret); +bool longlong_to_seval(long long v, se::Value* ret); +bool ssize_to_seval(ssize_t v, se::Value* ret); +bool std_string_to_seval(const std::string& v, se::Value* ret); + +bool Vec2_to_seval(const cocos2d::Vec2& v, se::Value* ret); +bool Vec3_to_seval(const cocos2d::Vec3& v, se::Value* ret); +bool Vec4_to_seval(const cocos2d::Vec4& v, se::Value* ret); +bool Mat4_to_seval(const cocos2d::Mat4& v, se::Value* ret); +bool Size_to_seval(const cocos2d::Size& v, se::Value* ret); +bool Rect_to_seval(const cocos2d::Rect& v, se::Value* ret); +bool Color3B_to_seval(const cocos2d::Color3B& v, se::Value* ret); +bool Color4B_to_seval(const cocos2d::Color4B& v, se::Value* ret); +bool Color4F_to_seval(const cocos2d::Color4F& v, se::Value* ret); +bool ccvalue_to_seval(const cocos2d::Value& v, se::Value* ret); +bool ccvaluemap_to_seval(const cocos2d::ValueMap& v, se::Value* ret); +bool ccvaluemapintkey_to_seval(const cocos2d::ValueMapIntKey& v, se::Value* ret); +bool ccvaluevector_to_seval(const cocos2d::ValueVector& v, se::Value* ret); +bool blendfunc_to_seval(const cocos2d::BlendFunc& v, se::Value* ret); +bool std_vector_string_to_seval(const std::vector& v, se::Value* ret); +bool std_vector_int_to_seval(const std::vector& v, se::Value* ret); +bool std_vector_float_to_seval(const std::vector& v, se::Value* ret); +bool std_vector_Touch_to_seval(const std::vector& v, se::Value* ret); +bool std_map_string_string_to_seval(const std::map& v, se::Value* ret); +bool uniform_to_seval(const cocos2d::Uniform* v, se::Value* ret); +bool FontDefinition_to_seval(const cocos2d::FontDefinition& v, se::Value* ret); +bool Acceleration_to_seval(const cocos2d::Acceleration* v, se::Value* ret); +bool Quaternion_to_seval(const cocos2d::Quaternion& v, se::Value* ret); +bool ManifestAsset_to_seval(const cocos2d::extension::ManifestAsset& v, se::Value* ret); +bool AffineTransform_to_seval(const cocos2d::AffineTransform& v, se::Value* ret); +bool Data_to_seval(const cocos2d::Data& v, se::Value* ret); +bool DownloadTask_to_seval(const cocos2d::network::DownloadTask& v, se::Value* ret); + +template +bool Vector_to_seval(const cocos2d::Vector& v, se::Value* ret); + +template +bool Map_string_key_to_seval(const cocos2d::Map& v, se::Value* ret); + +template +bool native_ptr_to_seval(typename std::enable_if::value,T>::type* v, se::Value* ret, bool* isReturnCachedValue = nullptr); + +template +bool native_ptr_to_seval(typename std::enable_if::value,T>::type* v, se::Class* cls, se::Value* ret, bool* isReturnCachedValue = nullptr) + +template +bool native_ptr_to_seval(typename std::enable_if::value,T>::type* v, se::Value* ret, bool* isReturnCachedValue = nullptr); + +template +bool native_ptr_to_seval(typename std::enable_if::value,T>::type* v, se::Class* cls, se::Value* ret, bool* isReturnCachedValue = nullptr); + +template +bool native_ptr_to_rooted_seval(typename std::enable_if::value,T>::type* v, se::Value* ret, bool* isReturnCachedValue = nullptr); + +template +bool native_ptr_to_rooted_seval(typename std::enable_if::value,T>::type* v, se::Class* cls, se::Value* ret, bool* isReturnCachedValue = nullptr); + + +// Spine conversions +bool speventdata_to_seval(const spEventData& v, se::Value* ret); +bool spevent_to_seval(const spEvent& v, se::Value* ret); +bool spbonedata_to_seval(const spBoneData& v, se::Value* ret); +bool spbone_to_seval(const spBone& v, se::Value* ret); +bool spskeleton_to_seval(const spSkeleton& v, se::Value* ret); +bool spattachment_to_seval(const spAttachment& v, se::Value* ret); +bool spslotdata_to_seval(const spSlotData& v, se::Value* ret); +bool spslot_to_seval(const spSlot& v, se::Value* ret); +bool sptimeline_to_seval(const spTimeline& v, se::Value* ret); +bool spanimationstate_to_seval(const spAnimationState& v, se::Value* ret); +bool spanimation_to_seval(const spAnimation& v, se::Value* ret); +bool sptrackentry_to_seval(const spTrackEntry& v, se::Value* ret); + +// Box2d +bool b2Vec2_to_seval(const b2Vec2& v, se::Value* ret); +bool b2Manifold_to_seval(const b2Manifold* v, se::Value* ret); +bool b2AABB_to_seval(const b2AABB& v, se::Value* ret); + +``` + +辅助转换函数不属于`Script Engine Wrapper`抽象层,属于cocos2d-x绑定层,封装这些函数是为了在绑定代码中更加方便的转换。 +每个转换函数都返回`bool`类型,表示转换是否成功,开发者如果调用这些接口,需要去判断这个返回值。 + +以上接口,直接根据接口名称即可知道具体的用法,接口中第一个参数为输入,第二个参数为输出参数。用法如下: + +```c++ +se::Value v; +bool ok = int32_to_seval(100, &v); // 第二个参数为输出参数,传入输出参数的地址 +``` + +```c++ +int32_t v; +bool ok = seval_to_int32(args[0], &v); // 第二个参数为输出参数,传入输出参数的地址 +``` + +#### (IMPORTANT)理解native\_ptr\_to\_seval与native\_ptr\_to\_rooted\_seval的区别 + +**开发者一定要理解清楚这二者的区别,才不会因为误用导致JS层内存泄露这种比较难查的bug。** + +* `native_ptr_to_seval`用于`JS控制CPP对象生命周期`的模式。当在绑定层需要根据一个CPP对象指针获取一个se::Value的时候,可调用此方法。引擎内大部分继承于`cocos2d::Ref`的子类都采取这种方式去获取se::Value。记住一点,当你管理的绑定对象是由JS控制生命周期,需要转换为seval的时候,请用此方法,否则考虑用`native_ptr_to_rooted_seval`。 +* `native_ptr_to_rooted_seval`用于`CPP控制JS对象生命周期`的模式。一般而言,第三方库中的对象绑定都会用到此方法。此方法会根据传入的CPP对象指针查找cache住的se::Object,如果不存在,则创建一个rooted的se::Object,即这个创建出来的JS对象将不受GC控制,并永远在内存中。开发者需要监听CPP对象的释放,并在释放的时候去做se::Object的unroot操作,具体可参照前面章节中描述的spTrackEntry_setDisposeCallback中的内容。 + ## 自动绑定