C binding experiments

Simplify conversion functions

Reorder padding/margin examples

Add getter example

Return error code rather than panicking on null style pointer

cargo fmt

Documentation get_style and with_style_mut macros

Split FFI into multiple files

Rename api module to style

Make style getters/setters unsafe

Add grid placement APIs

Prefix style methods with TaffyStyle

Move c bindings to an external crate

Eliminate boxes and raw pointers from C api

cargo fmt

Make function UpperCamelCase with underscore between struct name and function name

Use repr(C) instead of repr(u8)

Replace trbl function with function with dynamic edge parameter

Implement getters/setters for all non-grid numeric style properties

Format grid style

Update style size tests to include alignment

Add Overflow to prelude

Remove padding trbl function

Implement Display, Position, Overflow

Start generating bindings

Add style getters/setters for enum styles

Add abstraction for f32 getters/setters

Use individual unit and value for style value setters

Use TaffyStyleConstRef and TaffyStyleMutRef types

fmt + clippy

fmt prelude

Use generic result struct

Prefix enum variant names + make screaming snake case

Core: Add try_style_mut function to Taffy struct

Refactor error handling + add initial tree manipulation functions

Get "basic" example running via C bindings

Fix clippy lint

Allow AvailableSpace to be specified in TaffyTree_ComputeLayout

Exclude example binaries from git

Rename StyleValueUnit to TaffyUnit

Ensure all types are prefixed by Taffy

Add style getter/setters for grid row

Add TaffyTree_GetLayout method

Remove bindgen from compile_basic.sh

README WIP

README WIP

Fix build

Fix markdown lints

Fix bindings after rebase

Add ability to set measure function

Add script to regenerate header file

Add CI task to build C bindings example

Remove result types from style getters

Move c bindings to bindings/c directory

Fix build after rebase

Use nightly toolchain for c bindings (to enable cbindgen to work)

Fix c bindings ci

Ignore scratch dir

Signed-off-by: Nico Burns <[email protected]>

Author: nicoburns

.github/workflows/ci.yml

@@ -294,3 +294,19 @@ jobs:
         name: Build benchmarks (w/yoga)
         env:
           RUSTFLAGS: "-C opt-level=0"
+
+  build-c-bindings:
+    name: Build C Bindings
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - run: |
+          cd bindings/c
+          cargo build
+        name: Build ctaffy library
+      - run: |
+          cd bindings/c/examples
+          ./compile_basic.sh
+          LD_LIBRARY_PATH=$LD_LIBRARY_PATH:../../../target/debug ./basic
+        name: Build C Bindings

.gitignore

@@ -4,6 +4,7 @@
 /yoga_test_fixtures
 /yoga_test_fixtures_grouped
 /test_fixtures/_scratch
+_scratch
 
 **/*.rs.bk
 Cargo.lock

Cargo.toml

@@ -107,6 +107,7 @@ members = [
     "scripts/import-yoga-tests",
     "benches",
     "tests/common",
+    "bindings/c"
 ]
 # The cosmic_text example is excluded from the workspace as including it breaks compilation
 # of all crates in the workspace with our MSRV compiler

bindings/c/.gitignore

@@ -0,0 +1 @@
+examples/basic

bindings/c/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "ctaffy"
+version = "0.0.1"
+authors = [
+    "Nico Burns <[email protected]>",
+]
+edition = "2021"
+include = ["src/**/*", "Cargo.toml"]
+description = "C bindings to Taffy (A flexible UI layout library)"
+repository = "https://github.com/DioxusLabs/taffy"
+license = "MIT"
+
+[lib]
+name = "ctaffy"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[dependencies]
+taffy = { path = "../.." }

bindings/c/README.md

@@ -0,0 +1,97 @@
+# C API for Taffy (ctaffy)
+
+Taffy is a flexible, high-performance, cross-platform UI layout library written in Rust.
+
+This directory contains C bindings for Taffy. The API is a pure C API (no C++ features are used), and is designed to be easy to build other language bindings on top of. In addition to the documentation below, you may to read through the header file (`include/taffy.h`).
+
+## Examples
+
+There are readable examples in the examples directory.
+
+Assuming you have Rust and Cargo installed (and a C compiler), then this should work to run the basic example:
+
+```bash
+git clone https://github.com/DioxusLabs/taffy.git
+cd taffy/ctaffy/examples
+./compile-basic.sh
+./basic
+```
+
+## Naming Conventions
+
+- Everything in the Taffy C API is prefixed with `Taffy`, except enum variant names which are prefixed with `TAFFY_`
+- Structs and Enums are named in UpperCamelCase (e.g. `TaffyTree`, `TaffyStyle`)
+- Functions begin with the name of the struct they apply to, followed by an underscore, followed by the name of the function in UpperCamelCase (e.g. `TaffyTree_New`, `TaffyStyle_SetFlexBasis`)
+- Enum variants are SCREAMING_SNAKE_CASE
+
+## Error Handling
+
+Error handling is managed by the use of return codes and "result" structs. All functions in the API return either an `enum TaffyReturnCode` or one of the `struct Taffy*Result` structs (or `void` in the case of infallible operations that don't return anything).
+
+### Return codes
+
+Error handling is managed by the use of an enum `TaffyReturnCode`:
+
+```c
+typedef enum TaffyReturnCode {
+  TAFFY_RETURN_CODE_OK,
+  TAFFY_RETURN_CODE_NULL_STYLE_POINTER,
+  TAFFY_RETURN_CODE_NULL_TREE_POINTER,
+  // ... (see header file for full definition)
+} TaffyReturnCode;
+```
+
+`TAFFY_RETURN_CODE_OK` indicates that the operation succeeded. All other variant indicate
+
+### Result structs
+
+"Result structs" are used for functions that need to return another value in addition to a `TaffyReturnCode` indicating success/failure (such as style getters which need to return the relevant style value). As C doesn't support generic structs, there are several "Result structs": one for each type of value. But each struct follows the same structure as the following example (varying only in the name of the struct and the type of the `value` field):
+
+<table>
+<tr><th>TaffyIntResult</th><th>TaffyDimensionResult</th></tr>
+<tr>
+<td>
+
+```c
+typedef struct TaffyIntResult {
+  enum TaffyReturnCode return_code;
+  int32_t value;
+} TaffyIntResult;
+```
+
+</td>
+<td>
+
+```c
+typedef struct TaffyDimensionResult {
+  enum TaffyReturnCode return_code;
+  struct TaffyDimension value;
+} TaffyDimensionResult;
+```
+
+</td>
+</tr>
+</table>
+
+Functions that return Result structs will either return a `TAFFY_RETURN_CODE_OK` along with a meaningful value, or a error variant of `TaffyReturnCode` along with
+
+## API Usage
+
+### Tree Creation and Manipulation
+
+The `TaffyTree` struct is the entrypoint to the Taffy C API and represents an entire tree of UI nodes. Taffy uses arena allocation, so the `TaffyTree` owns the entire tree of nodes at all times.
+
+You only ever get access to a `TaffyNodeId` handle which can be used to manipulate the structure of the tree, or pointers to `TaffyStyle` object (which can be used to set styles on a Node, but are considered borrowed pointers and thus must only be held temporarily).
+
+#### Lifecycle
+
+- `TaffyTree_New` allocates a new `TaffyTree` and returns an owned pointer to it.
+- `TaffyTree_Free` can be used to free the tree once you are done with it.
+
+All other functions in the API which accept a pointer to a `TaffyTree` have borrowing semantics: they access the tree during the duration of the function (and if the pointer is not a `const` pointer, may modify the tree), but will not store the pointer or take ownership of the tree.
+
+#### Node creation and manipulation
+
+- `TaffyTree_NewNode` creates a new Node within the tree and returns a `TaffyNodeId` handle to it. The node will initially have the default styles
+
+### Setting styles on node

bindings/c/cbindgen.toml

@@ -0,0 +1,22 @@
+language = "c"
+cpp_compat = true
+documentation_style = "c99"
+line_length = 120
+
+[enum]
+rename_variants = "QualifiedScreamingSnakeCase"
+
+[export]
+include = ["TaffyNodeId"]
+
+[export.rename]
+TaffyResult_f32 = "TaffyFloatResult"
+TaffyResult_i32 = "TaffyIntResult"
+TaffyResult_TaffyNodeId = "TaffyNodeIdResult"
+TaffyResult_TaffyDimension = "TaffyDimensionResult"
+TaffyResult_TaffyGridPlacement = "TaffyGridPlacementResult"
+TaffyResult_TaffyStyleMutRef = "TaffyStyleMutRefResult"
+
+[parse.expand]
+crates = ["ctaffy"]
+

bindings/c/examples/basic.c

@@ -0,0 +1,41 @@
+#include <stdlib.h>
+#include <stdint.h>
+#include <math.h>
+#include <stdio.h>
+
+#include "taffy.h"
+
+int main() {
+    // Create tree
+    TaffyTree *tree = TaffyTree_New();
+
+    // Create child (+set styles)
+    TaffyNodeId child = TaffyTree_NewNode(tree).value;
+    TaffyStyle *child_style = TaffyTree_GetStyleMut(tree, child).value;
+    TaffyStyle_SetWidth(child_style, 0.5, TAFFY_UNIT_PERCENT);
+    TaffyStyle_SetHeight(child_style, 0, TAFFY_UNIT_AUTO);
+
+    // Create parent (+set styles)
+    TaffyNodeId parent = TaffyTree_NewNode(tree).value;
+    TaffyStyle *parent_style = TaffyTree_GetStyleMut(tree, parent).value;
+    TaffyStyle_SetWidth(parent_style, 100, TAFFY_UNIT_LENGTH);
+    TaffyStyle_SetHeight(parent_style, 100, TAFFY_UNIT_LENGTH);
+    TaffyStyle_SetJustifyContent(parent_style, TAFFY_ALIGN_CONTENT_CENTER);
+
+    // Setup parent-child relationship
+    TaffyTree_AppendChild(tree, parent, child);
+
+    // Compute layout (100x100 viewport)
+    printf("\nCompute layout with 100x100 viewport:\n");
+    TaffyTree_ComputeLayout(tree, parent, 100, 100);
+    TaffyTree_PrintTree(tree, parent);
+
+    // Compute layout (infinite viewport)
+    printf("\nCompute layout with infinite viewport:\n");
+    TaffyTree_ComputeLayout(tree, parent, INFINITY, INFINITY);
+    TaffyTree_PrintTree(tree, parent);
+
+    // Free tree
+    TaffyTree_Free(tree);
+    return 0;
+}

bindings/c/examples/compile_basic.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+set -ex
+
+cargo build --manifest-path ../Cargo.toml
+gcc -O3 -DDEBUG -o basic basic.c -std=c99 -Wall -I../include -L../../../target/debug -lctaffy

bindings/c/generate-bindings.sh

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+cbindgen --crate ctaffy --output include/taffy.h