Filament引擎分析--command抽象设备API
1. 前言
Filament中使用了FrameGraph来管理渲染管线，需要准备两点：
- 设备接口抽象：设备API抽象为Command
- 资源抽象：使用虚拟资源，在实际用到时再创建，方便剔除无用资源
下面就围绕Filament中设备API抽象为Command代码部分做一个解读：
2. 代码分析
先贴一段创建顶点缓冲的接口调用堆栈：
[Inlined] filament::backend::CommandBase::CommandBase(void (*)(filament::backend::Driver &, filament::backend::CommandBase *, int *)) CommandStream.h:63
[Inlined] filament::backend::CommandType<void (filament::backend::Driver::*)(filament::backend::Handle<filament::backend::HwVertexBuffer>, unsigned char, unsigned char, unsigned int, std::__ndk1::array<filament::backend::Attribute, 16u>)>::Command<&filament::backend::Driver::createVertexBufferR(filament::backend::Handle<filament::backend::HwVertexBuffer>, unsigned char, unsigned char, unsigned int, std::__ndk1::array<filament::backend::Attribute, 16u>)>::Command<filament::backend::Handle<filament::backend::HwVertexBuffer>, unsigned char, unsigned char, unsigned int, std::__ndk1::array<filament::backend::Attribute, 16u>>(void (*)(filament::backend::Driver&, filament::backend::CommandBase*, int*), filament::backend::Handle<filament::backend::HwVertexBuffer>&&, unsigned char&&, unsigned char&&, unsigned int&&, std::__ndk1::array<filament::backend::Attribute, 16u>&&) CommandStream.h:154
[Inlined] filament::backend::CommandStream::createVertexBuffer(unsigned char, unsigned char, unsigned int, std::__ndk1::array<…>) DriverAPI.inc:169
filament::FVertexBuffer::FVertexBuffer(filament::FEngine &, const filament::VertexBuffer::Builder &) VertexBuffer.cpp:185
[Inlined] utils::Arena::make<…>(filament::FEngine &, const filament::VertexBuffer::Builder &) Allocator.h:647
[Inlined] filament::FEngine::create<…>(filament::ResourceList<…> &, const filament::FVertexBuffer::Builder &) Engine.cpp:680
filament::FEngine::createVertexBuffer(const filament::VertexBuffer::Builder &) Engine.cpp:690
filament::FEngine::init() Engine.cpp:277
filament::FEngine::create(filament::backend::Backend, filament::backend::Platform *, void *, const filament::Engine::Config *) Engine.cpp:110
[Inlined] FilamentTest::setupFilament() FilamentTest.cpp:98
FilamentTest::init() FilamentTest.cpp:68
boxing::xr::composer::StartBase::instance(ANativeWindow *, int, int) StartBase.h:263
[Inlined] native_OnDrawFrame::$_0::operator()() const JniImpl.cpp:100
[Inlined] std::__ndk1::__invoke<…>(native_OnDrawFrame::$_0 &) type_traits:3874
[Inlined] std::__ndk1::__apply_functor<…>(native_OnDrawFrame::$_0 &, std::__ndk1::tuple<…> &, std::__ndk1::__tuple_indices<…>, std::__ndk1::tuple<…> &&) functional:2853
[Inlined] std::__ndk1::__bind::operator()<…>() functional:2886
[Inlined] std::__ndk1::__invoke<…>(std::__ndk1::__bind<…> &) type_traits:3874
std::__ndk1::__packaged_task_func::operator()() future:1817
[Inlined] std::__ndk1::__packaged_task_function::operator()() const future:1994
std::__ndk1::packaged_task::operator()() future:2214
[Inlined] std::__ndk1::__function::__value_func::operator()() const functional:1884
[Inlined] std::__ndk1::function::operator()() const functional:2556
<lambda>::operator()() const ThreadPool.h:71
[Inlined] decltype(std::__ndk1::forward<boxing::core::ThreadPool::ThreadPool(unsigned int)::'lambda'()>(fp)()) std::__ndk1::__invoke<boxing::core::ThreadPool::ThreadPool(unsigned int)::'lambda'()>(boxing::core::ThreadPool::ThreadPool(unsigned int)::'lambda'()&&) type_traits:3874
[Inlined] std::__ndk1::__thread_execute<…>(std::__ndk1::tuple<…> &, std::__ndk1::__tuple_indices<…>) thread:273
std::__ndk1::__thread_proxy<…>(void *) thread:284
__pthread_start(void*) 0x00000000eab36828
__start_thread 0x00000000eaaed5ce
渲染设备API定义：
filament\filament\backend\include\private\backend\DriverAPI.inc
DriverAPI.inc中使用大量的宏替换操作，将设备接口进行封装，或打包，这部分代码可读性极差，不过可从其调用逻辑来进行拆解和理解：
先来分析其中一个接口: createVertexBuffer 创建一个顶点缓冲
DECL_DRIVER_API_R_N(backend::VertexBufferHandle, createVertexBuffer,
uint8_t, bufferCount,
uint8_t, attributeCount,
uint32_t, vertexCount,
backend::AttributeArray, attributes)
这里不是真的创建，而要看这个宏接口在哪里使用，我们主要看看这两个地方：
CommandStream.h //命令流
Driver.h //设备接口
这两个文件中都对DriverAPI.inc进行了include，但是意义完全不一样，先看DECL_DRIVER_API_R_N：
#define DECL_DRIVER_API_R_N(R, N, ...) \
DECL_DRIVER_API_RETURN(R, N, PAIR_ARGS_N(ARG, ##__VA_ARGS__), PAIR_ARGS_N(PARAM, ##__VA_ARGS__))
关键在DECL_DRIVER_API_RETURN这个宏，在CommandStream.h和Driver.h头文件中include文件DriverAPI.inc 之前分别定义了自己的DECL_DRIVER_API_RETURN宏，看看CommandStream.h中：
#define DECL_DRIVER_API(methodName, paramsDecl, params) \
inline void methodName(paramsDecl) { \
DEBUG_COMMAND_BEGIN(methodName, false, params); \
using Cmd = COMMAND_TYPE(methodName); \
void* const p = allocateCommand(CommandBase::align(sizeof(Cmd))); \
new(p) Cmd(mDispatcher.methodName##_, APPLY(std::move, params)); \
DEBUG_COMMAND_END(methodName, false); \
}
#define DECL_DRIVER_API_SYNCHRONOUS(RetType, methodName, paramsDecl, params) \
inline RetType methodName(paramsDecl) { \
DEBUG_COMMAND_BEGIN(methodName, true, params); \
AutoExecute callOnExit([=](){ \
DEBUG_COMMAND_END(methodName, true); \
}); \
return apply(&Driver::methodName, mDriver, std::forward_as_tuple(params)); \
}
#define DECL_DRIVER_API_RETURN(RetType, methodName, paramsDecl, params) \
inline RetType methodName(paramsDecl) { \
DEBUG_COMMAND_BEGIN(methodName, false, params); \
RetType result = mDriver.methodName##S(); \
using Cmd = COMMAND_TYPE(methodName##R); \
void* const p = allocateCommand(CommandBase::align(sizeof(Cmd))); \
new(p) Cmd(mDispatcher.methodName##_, RetType(result), APPLY(std::move, params)); \
DEBUG_COMMAND_END(methodName, false); \
return result; \
}
上面三个宏的作用基本是一样的，都将要调用的函数和参数封装为了Command，不同之处在于DECL_DRIVER_API是command无返回值的，DECL_DRIVER_API_SYNCHRONOUS是封装为command后同步执行的，DECL_DRIVER_API_RETURN是需要返回值的
主要看看DECL_DRIVER_API_RETURN：
RetType result = mDriver.methodName##S();
将方法名后面拼接了S，调用拿到返回类型
看看拼接S后的实现：
Handle<HwVertexBuffer> OpenGLDriver::createVertexBufferS() noexcept {
return initHandle<GLVertexBuffer>();
}
initHandle()这句在filament内存池HandleArena上创建了一个GLVertexBuffer对象，然后根据内存地址创建了对象的唯一handeID
再看下面这句：
using Cmd = COMMAND_TYPE(methodName##R);
方法名后面拼接了R，然后获取了command的类型，没有执行方法，看看拼接R后的实现：
void OpenGLDriver::createVertexBufferR(
Handle<HwVertexBuffer> vbh,
uint8_t bufferCount,
uint8_t attributeCount,
uint32_t elementCount,
AttributeArray attributes) {
DEBUG_MARKER()
construct<GLVertexBuffer>(vbh, bufferCount, attributeCount, elementCount, attributes);
}
内存池HandleArena上创建了一个GLVertexBuffer对象
再看下面一句
void* const p = allocateCommand(CommandBase::align(sizeof(Cmd)));
new(p) Cmd(mDispatcher.methodName##_, RetType(result), APPLY(std::move, params));
在CommandStream内部的环形缓冲上申请了一块Command对象的内存p，然后在内存p上new了对象Command
看看CommandBase* execute执行函数的实现：
inline CommandBase* execute(Driver& driver) {
// returning the next command by output parameter allows the compiler to perform the
// tail-call optimization in the function called by mExecute, however that comes at
// a cost here (writing and reading the stack at each iteration), in the end it's
// probably better to pay the cost at just one location.
intptr_t next;
mExecute(driver, this, &next);
return reinterpret_cast<CommandBase*>(reinterpret_cast<intptr_t>(this) + next);
}
mExecute就是上面new(p) Cmd(mDispatcher.methodName##_, RetType(result), APPLY(std::move, params)); 后的函数和参数的封装体，然后拿到了下一个圆形缓冲中下一个command的地址偏移量next，返回下一个command地址
CommandStream中执行command，执行完然后获取下一个执行。。。
mDriver.execute([this, buffer]() {
Driver& UTILS_RESTRICT driver = mDriver;
CommandBase* UTILS_RESTRICT base = static_cast<CommandBase*>(buffer);
while (UTILS_LIKELY(base)) {
base = base->execute(driver);
}
});