love-clay

Native LÖVE integration for Clay.

Purpose and Scope

How do we combine LÖVE and Clay?

Specifically: How do we use LÖVE as a rendering backend for Clay?

Clay is a native (C) library. LÖVE however does not provide a stable external C or C++ API. Its maintainers describe the compatibility and maintenance constraints in love2d/love#1205. Calling LÖVE's internal C++ implementation would couple native modules to private APIs and an unstable ABI.

So this is going to be awkward either way.

(1) If we implement the renderer in Lua, we have to expose the render commands to the lua side and the user has to do the wiring.

(2) If we want to implement the renderer natively, we have to somehow interop with LÖVE natively.

This repository solves the second problem. It provides two header libraries:

• love_native_api.h, an adapter for invoking LÖVE's Lua-facing API from a native Lua module.
• love_clay_renderer.h, a native renderer that consumes Clay_RenderCommandArray directly and draws it through that adapter.

This can then be used in a higher-level native GUI library that uses Clay for layout while interoperating with LÖVE through this renderer.

This repository does not provide Lua bindings for Clay.

If you were interested in the first problem consider revolucas/clay_lua_bindings, which exposes Clay layout construction and render commands to Lua. Then write the LÖVE renderer on the Lua side.

Side Note There is a theoretical third option. Because clay_lua_bindings is distributed as a single C source file, it can be compiled together with love_clay_renderer.h in one Lua module. A small Lua-facing native function can call Clay_EndLayout(), pass the resulting native Clay_RenderCommandArray directly to LoveClayRenderer_Render(), and expose the combined operation to Lua. This sidesteps the need to implement the renderer in Lua while still using mostly the existing Clay bindings that come without a renderer.

Current renderer status

Incomplete. Rectangles and text are currently supported.

Development setup

love-clay is built inside the love-native-modules workspace so it uses the same LuaJIT and native toolchain as the local LÖVE build. Set up that repository first by following its README.

From the workspace root, clone this repository and Clay into the expected locations:

git clone https://github.com/MM1nd/love-clay.git modules/love-clay
git clone https://github.com/nicbarker/clay.git modules/love-clay/deps/clay

Native Smoke Test

The example builds as clay_smoke.dll.

After building and packaging the workspace, run:

.\dist\love\Release\love.exe --console .\modules\love-clay\examples\smoke

License

love-clay is distributed under the BSD 3-Clause License. See LICENSE.