API 慣例

在使用 EasyAR Sense 的 API 時，需要遵循一些慣例，否則可能會引起程序崩潰、出現內存泄漏或其他運行不正常的情況。

支持的語言

EasyAR Sense 支持如下語言：

• C

  支持 C99 和 Visual C++、gcc、clang

• C++

  支持 C++17 和 Visual C++、gcc、clang

  用到的 C++17 特性只有 std::optional，如果需要在 C++11 環境使用，可以使用 optional lite，將接口頭文件中的 std::optional 替換爲 nonstd::optional，並將 #include <optional> 替換爲#include "nonstd/optional.hpp"

• Java

  僅支持 Android 平臺，支持 Java SE 6 及以上

• Kotlin

  僅支持 Android 平臺

• Objective-C

  僅支持 iOS/macOS/visionOS 平臺

• Swift

  支持 Swift 4.2 及以上

• C#

  支持 .Net Framework 3.5 及以上、.Net Core、.Net 5+、Mono、Unity/Mono、Unity/IL2CPP

線程安全模型

每個類，如果不加說明，則其靜態成員是線程安全的。

每個類，如果不加說明，則其實例成員在外部加鎖的情況下是線程安全的，在不加鎖的情況下不是線程安全的。

每個類，如果不加說明，則在結束對對象的其他調用後，可以從任意線程調用其析構函數，此時是線程安全的。

內存模型

EasyAR Sense 內部使用 C++ 的 std::shared_ptr 進行引用計數，而引用計數和垃圾回收之間存在着根本上的不兼容，不能無縫轉換。

• C, C#, Java/Kotlin

  需要進行手動引用計數，使用 dispose 釋放持有的對象的引用，使用 clone 從一個引用創建一個新的引用。

  特別需要注意的是傳入到 EasyAR Sense 的回調的參數會在回調結束後自動釋放，如果需要保留必須進行 clone，自動釋放的原因是爲了支持傳入沒有任何邏輯的回調。

  需要注意的是傳入到 EasyAR Sense 的回調中如果使用到 EasyAR Sense 的對象可能導致循環引用，需要當成資源（例如文件、操作系統句柄）進行手動釋放，防止內存泄漏。

• C++, Objective-C, Swift

  使用語言內置的引用計數。

  需要注意的是傳入到 EasyAR Sense 的回調中如果使用到 EasyAR Sense 的對象可能導致循環引用，應合理使用引用捕捉、std::weak_ptr 等。

字符串編碼

接口中使用的字符串的編碼如下：

• C, C++

  UTF-8

• Java, Kotlin, Objective-C, C#

  UTF-16

• Swift

  UTF-16 或者 UTF-8, 參考 Swift文檔