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文件