行业资讯
Unity安卓开发：调用C/C++ .so库实现高性能与SDK集成
1. 项目概述为什么要在Unity里调用C/C的.so库如果你是一个Unity开发者尤其是在做安卓游戏或者应用的时候可能遇到过这样的场景项目里需要一个高性能的数学计算模块或者要集成一个用C写的、已经非常成熟的第三方SDK比如人脸识别、音视频编解码库又或者有一段对性能要求极高的核心算法逻辑。直接用C#写要么性能达不到要求要么根本找不到现成的库。这时候一个很自然的想法就是能不能让Unity去调用那些用C/C编译好的、现成的动态链接库在安卓上就是.so文件这个想法完全可行而且在实际开发中非常普遍。我做过不少需要深度优化或者集成硬件SDK的项目几乎都绕不开这一步。Unity作为一个强大的游戏引擎和内容创作平台其核心优势在于高效的渲染管线、丰富的组件系统和跨平台部署能力。但对于底层系统交互、特定硬件加速或遗留的C/C代码库直接通过C#去实现要么困难重重要么效率低下。通过libname.so这种动态库进行交互就相当于为Unity项目打开了一扇通往底层系统和高性能计算的后门。简单来说这个过程就是你用C/C写好核心功能编译成安卓平台能识别的.so动态库然后在Unity的C#脚本里通过一套名为“平台调用”Platform Invoke 简称P/Invoke的机制去调用这个库里的函数。这能让你的Unity应用既保有快速开发、所见即所得的优势又能榨干设备的硬件性能复用庞大的C/C生态。接下来我就把自己趟过的路、踩过的坑以及如何稳定高效地实现这套交互的完整经验分享出来。2. 核心交互原理与架构设计在动手写代码之前我们必须把UnityC#与C/C.so之间是怎么“搭上话”的原理搞清楚。这就像两个说不同语言的人要合作得先定好沟通的协议。2.1 沟通的桥梁P/Invoke与[DllImport]Unity或者说.NET/Mono环境调用本地原生代码依赖的是P/Invoke机制。在C#中我们通过[DllImport]这个属性来声明一个外部函数。这个属性会告诉运行时“嘿这个函数的实际实现不在咱们C#这边在一个叫‘XXX.so’的动态库里你按照我给的规则去找到它并调用。”一个最简单的声明长这样using System.Runtime.InteropServices; public class NativeWrapper { [DllImport(MyNativeLib)] public static extern int Add(int a, int b); }这里“MyNativeLib”就是动态库的名字运行时系统会自动补上平台相关的前缀和后缀比如在安卓上会寻找libMyNativeLib.so。Add方法必须标记为static extern表示它是一个外部静态方法。2.2 数据类型的“翻译官”MarshalingC#和C/C有着完全不同的数据类型系统。C#有丰富的类、字符串、数组等而C/C那边是原始的内存指针、结构体。直接传递一个C#的string对象给C函数是行不通的。这就需要“列集”Marshaling过程来当翻译。Marshaling负责在托管环境C#和非托管环境C/C之间转换数据。[DllImport]属性里可以指定如何列集参数和返回值。例如[DllImport(MyNativeLib, CharSet CharSet.Ansi)] public static extern IntPtr CreateMessage(string text); [DllImport(MyNativeLib)] public static extern void ProcessBuffer(byte[] data, int length);CharSet CharSet.Ansi告诉系统把C#的string转换成C/C里以\0结尾的ANSI字符串char*。byte[]作为参数时P/Invoke默认会将其锁定在内存中并传递指向其首字节的指针给C函数。int length通常需要显式传递因为C那边不知道数组长度。对于复杂类型如结构体你需要确保C#中的结构体布局与C/C中的完全一致这就要用到[StructLayout(LayoutKind.Sequential)]属性来保证字段在内存中的顺序和大小是对齐的。2.3 安卓平台的特殊性ABI与放置路径在Windows上动态库是.dll在macOS上是.dylib而在安卓上就是.so。安卓的.so库还有一个关键概念ABIApplication Binary Interface 应用二进制接口。不同的CPU架构如armeabi-v7a arm64-v8a x86 x86_64需要编译对应版本的.so文件。你的Unity项目最终打包成APK时需要为所有目标设备支持的ABI提供相应的库文件。在Unity项目中.so库文件的放置位置有严格规定Assets/Plugins/Android目录下这是主目录。在Android目录下按照ABI创建子文件夹如libs/armeabi-v7alibs/arm64-v8alibs/x86等。注意有些旧资料或IDE可能会生成jniLibs文件夹但在Unity的打包流程中libs目录是标准且被自动识别的。你应该把编译好的libMyNativeLib.so文件放到对应的ABI子目录下例如Assets/Plugins/Android/libs/arm64-v8a/libMyNativeLib.so。重要心得很多初次尝试者遇到的“DllNotFoundException”错误十有八九是因为.so文件放错了位置或者文件名不匹配。Unity在构建安卓项目时会将这些libs下的.so文件自动打包进APK的lib/abi/目录中。确保你的目录结构和ABI分类正确无误。2.4 整体架构设计思路一个稳健的交互架构通常分为三层原生层C/C负责核心算法、硬件操作、高性能计算或第三方SDK封装。这一层编译产出各ABI版本的.so文件。关键是要设计好清晰、稳定的C接口。桥接层C# P/Invoke包装在Unity中创建专门的类如NativePlugin.cs使用[DllImport]声明所有需要调用的原生函数。这一层只做最简单的数据列集和函数转发不包含业务逻辑。业务层Unity C#游戏或应用的逻辑层。通过调用桥接层提供的静态方法来使用原生功能。业务层应该感知不到原生调用的复杂性就像调用普通C#方法一样。这种分层设计解耦了原生代码和Unity逻辑使得原生库可以独立开发、测试和更新也便于处理平台差异。3. 从零开始创建与编译安卓可用的.so库理论懂了我们开始动手。首先你需要一个能编译出安卓平台.so库的环境。3.1 工具链选型NDK是关键安卓的C/C代码编译离不开NDKNative Development Kit。NDK包含了交叉编译器gcc/clang、库文件、构建脚本等一切所需。为什么不用普通的GCC/Visual Studio因为你的开发机通常是x86架构的Windows/Mac/Linux和安卓设备ARM架构的CPU指令集不同需要交叉编译。如何获取NDK通过Android Studio安装Android Studio后在SDK Manager的“SDK Tools”标签页中勾选“NDK (Side by side)”和“CMake”进行安装。这是最推荐的方式管理方便。独立下载从安卓开发者官网下载独立NDK包并配置系统环境变量。我推荐使用Android Studio来管理NDK因为它能很好地处理版本和路径问题。记下你的NDK安装路径比如C:\Users\YourName\AppData\Local\Android\Sdk\ndk\25.1.8937393。3.2 编写一个简单的C接口原生库的接口设计至关重要。为了最大的兼容性和易用性强烈建议使用纯C语言来编写对外暴露的函数接口而不是C。因为C的ABI函数名修饰、调用约定比C简单稳定得多几乎所有语言包括C#都能更容易地调用C接口。如果你用C实现内部逻辑可以用extern C来包裹导出函数防止C的名称修饰Name Mangling。创建一个头文件native-lib.h:#ifndef NATIVE_LIB_H #define NATIVE_LIB_H // 标记函数为可导出且使用C语言的链接规范 #ifdef __cplusplus extern C { #endif // 声明一个简单的加法函数 int add(int x, int y); // 声明一个处理字符串的函数 // 注意调用者需负责释放返回的字符串内存 const char* getGreeting(const char* name); // 声明一个处理数组数据的函数 void processArray(float* inputArray, int length, float* outputArray); #ifdef __cplusplus } #endif #endif //NATIVE_LIB_H再创建实现文件native-lib.c(或.cpp):#include native-lib.h #include stdio.h #include string.h #include malloc.h int add(int x, int y) { return x y; } const char* getGreeting(const char* name) { // 这是一个简单的例子。在实际项目中从C函数返回字符串需要谨慎管理内存。 // 这里我们返回一个静态字符串简单但非线程安全。 // 更安全的做法是让C#调用方分配缓冲区并传入。 static char greeting[256]; snprintf(greeting, sizeof(greeting), Hello from C, %s!, name); return greeting; } void processArray(float* inputArray, int length, float* outputArray) { if (inputArray NULL || outputArray NULL || length 0) { return; } for (int i 0; i length; i) { outputArray[i] inputArray[i] * 2.0f; // 示例操作每个元素乘以2 } }3.3 使用CMake进行跨平台构建手动调用NDK编译器命令非常繁琐。现代的做法是使用CMake来管理构建过程。CMake是一个跨平台的构建系统生成器可以为你生成适合当前平台的构建脚本如Makefile Ninja文件。创建一个CMakeLists.txt文件和你的源代码放在一起cmake_minimum_required(VERSION 3.18.1) project(MyNativeLib) # 项目名会影响生成的库文件名 # 设置C标准 set(CMAKE_C_STANDARD 11) # 添加一个库目标SHARED 表示动态库my_native_lib是逻辑名 add_library(my_native_lib SHARED native-lib.c) # 指定库的输出名。最终生成的库文件将是 libMyNativeLib.so set_target_properties(my_native_lib PROPERTIES OUTPUT_NAME MyNativeLib) # 查找并链接必要的库比如log库用于安卓调试输出 find_library(log-lib log) # 将log库链接到我们的目标 target_link_libraries(my_native_lib ${log-lib})3.4 编译生成多ABI版本的.so文件有了CMake文件我们就可以用NDK的工具链来编译了。虽然可以在命令行完成但对于新手我推荐在Android Studio中创建一个简单的“Native C”项目模板然后把我们的native-lib.c和CMakeLists.txt替换进去直接构建。这样最省心。如果你想用命令行基本步骤如下以Windows NDK r25为例打开终端进入项目目录。为每个ABI创建构建目录并编译# 配置和编译 arm64-v8a mkdir build_arm64 cd build_arm64 cmake -DCMAKE_TOOLCHAIN_FILE%ANDROID_NDK%\build\cmake\android.toolchain.cmake ^ -DANDROID_ABIarm64-v8a ^ -DANDROID_PLATFORMandroid-24 .. cmake --build . # 回到上级目录编译 armeabi-v7a cd .. mkdir build_armv7 cd build_armv7 cmake -DCMAKE_TOOLCHAIN_FILE%ANDROID_NDK%\build\cmake\android.toolchain.cmake ^ -DANDROID_ABIarmeabi-v7a ^ -DANDROID_PLATFORMandroid-24 .. cmake --build .编译完成后你会在build_abi/目录下找到libMyNativeLib.so文件。将不同ABI的.so文件分别放入Unity项目的Assets/Plugins/Android/libs/abi/目录下。踩坑实录ANDROID_PLATFORMandroid-24指定了最低API级别。这个值必须与你Unity项目Player Settings中设置的Minimum API Level相匹配或更低否则可能导致库无法加载。务必检查并保持一致。4. Unity端的集成与调用实战原生库准备好了现在轮到Unity上场了。4.1 创建C#包装类在Unity项目中创建一个C#脚本比如NativePlugin.cs。这个类就是我们的桥接层。using System; using System.Runtime.InteropServices; using System.Text; using UnityEngine; public static class NativePlugin { // 1. 声明add函数 // 库名就是MyNativeLibUnity会自动在安卓上查找libMyNativeLib.so [DllImport(MyNativeLib)] public static extern int add(int x, int y); // 2. 声明getGreeting函数 // CharSet.Ansi 表示传递ANSI字符串C中的char* // CallingConvention.Cdecl 是C/C默认的调用约定通常需要指定 [DllImport(MyNativeLib, CharSet CharSet.Ansi, CallingConvention CallingConvention.Cdecl)] public static extern IntPtr getGreeting(string name); // 3. 声明processArray函数 // 对于数组我们通常传递指针和长度 // 使用[In]和[Out]属性可以明确数据流向非必须但更清晰 [DllImport(MyNativeLib, CallingConvention CallingConvention.Cdecl)] public static extern void processArray([In] float[] inputArray, int length, [Out] float[] outputArray); // 一个辅助方法将IntPtr从C返回的char*转换为C# string public static string GetGreetingString(string name) { IntPtr ptr getGreeting(name); return Marshal.PtrToStringAnsi(ptr); // 转换ANSI字符串 } }4.2 在MonoBehaviour中调用测试创建一个测试脚本NativeTest.cs挂到场景中的GameObject上。using UnityEngine; public class NativeTest : MonoBehaviour { void Start() { Debug.Log([NativeTest] Starting native library calls...); // 测试1: 简单的加法 int sum NativePlugin.add(5, 3); Debug.Log($5 3 {sum} (from native lib)); // 测试2: 字符串交互 string greeting NativePlugin.GetGreetingString(Unity Developer); Debug.Log($Greeting from C: {greeting}); // 测试3: 数组处理 float[] input { 1.0f, 2.0f, 3.0f, 4.0f, 5.0f }; float[] output new float[input.Length]; NativePlugin.processArray(input, input.Length, output); Debug.Log(Array processing result:); for (int i 0; i output.Length; i) { Debug.Log($ output[{i}] {output[i]}); } } }4.3 配置Unity的Player Settings在打包安卓APK前需要对Unity的构建设置进行关键配置打开File - Build Settings 选择Android平台点击Switch Platform。点击Player Settings... 打开Player Settings窗口。在Other Settings区域Scripting Backend 选择IL2CPP。IL2CPP比旧的Mono后端在性能和安全性上更好对原生交互的支持也更稳定。这是当前Unity开发安卓项目的强烈推荐选项。Target Architectures 勾选你提供了.so库的ABI。例如如果你有arm64-v8a和armeabi-v7a的库就同时勾选ARM64和ARMv7。只勾选你确实提供了库的架构可以减小APK体积。Minimum API Level 确保这个版本号不高于你编译.so库时使用的ANDROID_PLATFORM版本。如前所述保持一致最安全。4.4 构建、部署与真机调试构建APK在Build Settings中点击Build生成.apk文件。安装到手机通过USB调试或ADB命令安装APK。查看日志这是调试原生交互问题的生命线。使用adb logcat命令在终端查看设备日志或者在Unity编辑器中打开Android Logcat窗口Window - Analysis - Android Logcat。你需要过滤Unity标签或者搜索你的日志关键词如[NativeTest]。验证库加载如果一切正常你将在日志中看到你的调试输出。如果库加载失败你会看到类似DllNotFoundException: MyNativeLib的错误。这时请回头检查.so文件是否放到了正确的Assets/Plugins/Android/libs/abi/目录库文件名是否正确应该是libMyNativeLib.so在C#中声明时去掉lib前缀和.so后缀ABI配置是否匹配你的C函数是否被正确定义和导出可以用nm或readelf工具查看.so文件中的符号5. 进阶技巧与深度避坑指南掌握了基础流程下面这些进阶知识和“坑点”能让你在实战中更加游刃有余。5.1 复杂数据类型的传递结构体与回调函数传递和返回结构体 需要在C#中定义一个与C结构体内存布局完全一致的结构体并使用[StructLayout(LayoutKind.Sequential)]。// C端结构体 typedef struct { int id; float x, y, z; } Vector3Data;// C#端对应结构体 [StructLayout(LayoutKind.Sequential)] public struct Vector3Data { public int id; public float x; public float y; public float z; } [DllImport(MyNativeLib)] public static extern Vector3Data GetVectorData(int id);从C#传递回调函数到C 这允许C/C代码在特定事件发生时回调你的C#方法。这非常有用比如用于异步通知、事件监听等。// C端定义一个函数指针类型 typedef void (*LogCallback)(const char* message); // 一个设置回调的函数 void setLogCallback(LogCallback callback);// C#端定义与C函数指针匹配的委托 [UnmanagedFunctionPointer(CallingConvention.Cdecl)] public delegate void LogCallbackDelegate(string message); [DllImport(MyNativeLib)] public static extern void setLogCallback(LogCallbackDelegate callback); // 使用方法 void Start() { setLogCallback(OnNativeLog); } private void OnNativeLog(string msg) { Debug.Log($[Native Log]: {msg}); }关键点必须使用[UnmanagedFunctionPointer]属性指定调用约定通常为Cdecl并且要确保委托实例在生命周期内不会被垃圾回收器回收通常将其保存为类的成员变量。5.2 内存管理谁分配谁释放这是原生交互中最容易出错和导致崩溃的地方。必须严格遵守一个黄金法则在哪个环境分配的内存就在哪个环境释放。C分配C释放如果C函数返回一个指针如malloc分配的内存并且C#需要长期使用那么C#必须将这个指针保存为IntPtr。当不再需要时必须调用另一个C函数如freeMemory(void* ptr)来释放它。绝对不要在C#端尝试用Marshal.FreeHGlobal等方法来释放由C的malloc分配的内存反之亦然。跨环境的内存分配器不同混用必然崩溃。C#分配C使用如果C函数需要填充一个缓冲区最佳实践是由C#分配好数组如byte[]或float[]并传入。C函数只负责向这个已分配的内存中写入数据。这样内存的生命周期由C#的GC管理最安全。5.3 线程安全原生代码在什么线程运行Unity的脚本如UpdateStart运行在主线程渲染线程。当你通过P/Invoke调用一个C函数时默认情况下该C函数的执行会阻塞调用它的C#线程也就是主线程。如果你的C函数执行的是耗时操作如图像处理、复杂计算这会导致游戏卡顿。解决方案在C/C侧创建线程在C函数内部使用std::thread或pthread创建新线程执行耗时任务然后立即返回。任务完成后通过回调函数见5.1通知C#主线程。注意从非主线程回调到C#时不能直接操作Unity对象如GameObjectDebug.Log需要通过UnityEngine.UnitySynchronizationContext或MainThreadDispatcher等方式将任务派发回主线程执行。在C#侧使用多线程使用C#的Task或Thread在新线程中调用P/Invoke函数。同样需要注意从这些线程不能直接访问Unity API。血泪教训我曾在一个音频处理项目中直接在Update里调用一个做FFT的C函数导致游戏帧率骤降。后来改为C内部开工作线程处理并通过环形缓冲区和回调传递结果性能立刻平滑。多线程是高性能原生交互的必修课但线程同步和与Unity主线程的通信是难点设计时要格外小心。5.4 调试.so库Logcat与addr2line当你的应用在调用原生库时崩溃发生SIGSEGV段错误等Unity的日志可能只显示一个模糊的错误。这时需要借助安卓的logcat和NDK工具进行深度调试。在C/C代码中添加日志使用__android_log_print函数需要包含android/log.h头文件并链接log库。这能让你在logcat中看到原生代码的执行路径。#include android/log.h #define LOG_TAG MyNativeLib #define LOGI(...) __android_log_print(ANDROID_LOG_INFO, LOG_TAG, __VA_ARGS__) #define LOGE(...) __android_log_print(ANDROID_LOG_ERROR, LOG_TAG, __VA_ARGS__) void myFunction() { LOGI(Entering myFunction); // ... your code ... if (error) { LOGE(Something went wrong! Error code: %d, errCode); } }分析崩溃堆栈当崩溃发生时logcat会输出一个原生堆栈跟踪native stack trace但地址是混乱的。你需要使用NDK中的addr2line或ndk-stack工具来将这些地址还原成代码文件和行号。将崩溃日志保存到文件crash.log。使用命令ndk-path/toolchains/llvm/prebuilt/host/aarch64-linux-android-addr2line -e path-to-your-so/libMyNativeLib.so -f -C memory-address-from-log来解析单个地址。更简单的方法是使用ndk-stackndk-path/ndk-stack -sym path-to-your-so-files-directory -dump crash.log。它会自动解析整个堆栈。5.5 性能优化要点减少P/Invoke调用开销每次P/Invoke调用都有固定的开销。避免在每帧循环中如Update调用大量细小的原生函数。应该将数据批量处理一次调用完成更多工作。固定Pin数组当传递大型数组如图像数据时GC可能会在C函数执行期间移动数组内存导致错误。可以使用GCHandle.Alloc(array, GCHandleType.Pinned)来固定数组获取指针调用结束后再Free。或者对于频繁操作的数据考虑在非托管侧C分配和管理内存。使用unsafe代码和指针对于极致性能场景可以在C#中使用unsafe上下文和指针直接操作内存与原生代码共享内存块避免数据拷贝。但这需要极高的谨慎容易引发内存安全问题。6. 常见问题排查速查表在实际开发中你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了表格方便快速查阅。问题现象可能原因排查步骤与解决方案DllNotFoundException: MyNativeLib1..so文件未放入正确目录。2. 文件名不匹配。3. 依赖的其它.so库缺失。4. ABI不兼容。1. 确认.so文件在Assets/Plugins/Android/libs/abi/下。2. 确认C#中[DllImport(“MyNativeLib”)]的名字与.so文件名匹配去掉lib前缀和.so后缀。3. 使用readelf -d libMyNativeLib.so查看依赖确保所有依赖库都存在。4. 检查Player Settings中的Target Architectures是否包含设备ABI且已提供对应库。Application crashed on native call1. 内存访问越界使用空指针、野指针。2. 堆栈溢出。3. 数据类型/结构体对齐不匹配。4. 调用约定错误。1. 检查C/C代码中的所有指针操作确保有效性。2. 检查递归函数或过大的局部变量。3. 仔细核对C#与C/C结构体的字段顺序、类型和大小。使用sizeof在两边打印对比。4. 在[DllImport]中显式指定CallingConvention.CdeclC/C默认。传递/返回字符串时乱码或崩溃1. 字符编码不一致。2. 内存管理错误如返回局部变量地址。1. 确保[DllImport]的CharSet与C端一致Ansi或Unicode。安卓C库通常用UTF-8可尝试CharSet CharSet.Ansi。2. 不要从C函数返回指向局部变量的字符串指针。应返回静态字符串、全局字符串或由调用者传入缓冲区。回调函数Delegate不执行或导致崩溃1. 委托实例被垃圾回收。2. 从非主线程回调并访问了Unity API。1. 将委托实例保存为类的静态或成员变量防止GC回收。2. 在回调中先将数据保存然后通过UnityEngine.UnitySynchronizationContext.Post或自己实现的派发器将实际逻辑抛回主线程执行。在Editor中运行正常打包后失败1. Editor运行在桌面环境加载的是不同版本的库如.dll。2. 打包脚本或Post-Process脚本有问题。1. 使用#if UNITY_ANDROID !UNITY_EDITOR来条件编译安卓专用的原生调用代码在Editor模式下使用模拟实现或直接跳过。2. 检查构建管线确保.so文件被正确复制到libs目录。性能低下调用原生函数时卡顿1. P/Invoke调用过于频繁。2. 原生函数本身是耗时操作阻塞主线程。1. 合并调用批量处理数据。2. 将耗时原生函数改为异步模式在C侧创建线程执行通过回调返回结果。最后我想分享一个最深刻的体会Unity与原生代码的交互稳定性远比炫技重要。尤其是在移动平台一次未经处理的原生层崩溃会导致整个应用闪退用户体验极差。因此务必在原生代码中加入充分的错误检查、边界判断和日志输出在C#端则要用try-catch包裹关键的P/Invoke调用并设计好降级方案比如原生功能失效时切换回纯C#的逻辑哪怕慢一点。把交互的边界定义清晰把内存和线程管理好剩下的就是享受它带来的性能红利和生态便利了。这套技术栈是连接Unity高效开发与底层硬件能力的坚实桥梁用好了你的项目能力边界将得到巨大的拓展。
郑州网站建设
网页设计
企业官网
)
![[具身智能-634]：Python 封装的地平线 VIO 多媒体库：libsrcampy库详解](http://pic.xiahunao.cn/yaotu/[具身智能-634]：Python 封装的地平线 VIO 多媒体库：libsrcampy库详解)
