README.org

c.thi.ng

Contents

• c.thi.ng
  • Overview
    • Data structures
    • Memory management
    • Math
    • Simulation
    • Geometry
  • Requirements
  • Dependencies
  • Examples
    • Build all examples
    • 1D/2D Cellular automata
    • Convex Hull
    • Diffusion-Limited Aggregation
    • GLFW (desktop & emscripten)
    • Poisson disc sampling image conversion
    • Polygon clipping (Greiner-Hormann)
    • Polygon offsetting
    • Verlet physics
    • Voronoi
  • Build & test
  • Build static library
  • Build source x-ref
  • Disassemble & list symbols
  • Compile with emscripten
    • Build as library for emcc
    • Run test suite in browser
  • Build customization
  • Contributors
  • License

Overview

WIP

Data structures

• Adjacency matrix (undirected graph)
• Cons list (with & without reference counting)
• Hashset (generic)
• Hashtable (generic)
• Object wrapper & protocol dispatch
• Octree
• Quadtree
• Spatial grid (1D, 2D, 3D)
• Structure of Array (SOA) wrapper & vector ops (SSE, AVX & serial)

Memory management

• Memory pool (auto-growth, manual compacts)
• Reference counting utils

Math

• Murmur Hash (32bit version)
• Poisson disc sampling

Simulation

• Cellular Automata (1D/2D, w/ adjustable kernel sizes)
• Verlet physics (2D particles)

Geometry

• Convex Hull (2D)
• Matrix 4x4 (w/ opt SSE impls)
• Vec2/3/4 (w/ opt SSE impls)
• Vector swizzling
• Line clipping (Liang-Barsky)
• Polygon (2D)
  • Polygon clipping (Greiner-Hormann)
  • Polygon offsetting / insetting
• Voronoi (2D)

…

TBD

Requirements

• Premake5
• GNU Make
• GCC / Clang (w/ C11 support)
• fswatch (only needed for ./autotest runner)
• emscripten & node (only needed for asm.js x-compilation via ./compile & ./compile-bc)
• cscope (only needed for ./browse)
• rsvg & ffmpeg (only needed for ./makevideo)

Dependencies

The library itself has no 3rd party dependencies. Some of the examples however use these additional libs:

• ct-head (included as submodule)
• stb_image (bundled under /examples/common)
• GLFW3.2+

Examples

Build all examples

git clone --recursive https://github.com/thi-ng/c-thing

premake5 gmake
make config=release_sse

1D/2D Cellular automata

Source (1D) | Source (2D)

# build library & example app
make config=release_sse ex-ca1d

# 1D sample invocation w/ Wolfram Rule 105
# Result will be written to /assets/ca-105.svg
# args: rule states kernelwidth res
bin/release/ex-ca1d 105 2 1

# Output all 255 wolfram rules
for i in {1..255}; do bin/release/ex-ca1d $i 2 1 128; done

# Another example w/ bigger kernel size
bin/release/ex-ca1d 522530942 32 3 128

# build 2D example app
make config=release_sse ex-ca2d

# frames will be written to /assets
bin/release/ex-ca2d

Convex Hull

Source

# build library & example app
make config=release_sse ex-chull && bin/release/ex-chull > assets/chull.svg

Diffusion-Limited Aggregation

Source

# build library & example app
make config=release_sse ex-dla && bin/release/ex-dla > assets/dla.svg

GLFW (desktop & emscripten)

Source | Online demo

See dependencies for details…

# build library & example app
make config=release_sse ex-glfw01 && bin/release/ex-glfw01

Note: Desktop version currently only has build settings for OSX.

To compile with Emscripten & open in browser: http://localhost:8000/glfw.html

# build LLVM bitcode of library (./obj/libcthing.bc)
./compile-bc

# compile example for browser & link with lib
emcc -O2 -DCT_FEATURE_LOG -DCT_NO_EXPORT -DNDEBUG \
     -s 'USE_GLFW=3' \
     -s 'ELIMINATE_DUPLICATE_FUNCTIONS=1' \
     -s 'NO_EXIT_RUNTIME=1' \
     --llvm-lto 1 \
     --closure 1 \
     --preload-file assets/suzanne.stl \
     -Isrc -Iext \
     -o glfw.html \
     examples/glfw/*.c obj/libcthing.bc

# launch server
python -m SimpleHTTPServer

Poisson disc sampling image conversion

Source

# build library & example app
make config=release_sse ex-poisson

# show usage
bin/release/ex-poisson
# Missing input file
# Usage:  ex-poisson [options] image [ > out.svg ]
#   -b HEX    bg color (default: ffffff)
#   -f HEX    fg color (default: 0000ff)
#   -g FLOAT  gamma (default: 3.00)
#   -i        invert (also swaps fg/bg) (default: no)
#   -m FLOAT  min distance (default: 2.00)
#   -x FLOAT  max distance (default: 10.00)
#   -r FLOAT  dot radius (default: 1.00)
#   -q INT    quality (default: 100)
#   -t        output points as text only (default: no)

# concrete example (for image size roughly 700x1000px)
bin/release/ex-poisson -g 1.25 -q 500 -m 1.5 -x 16 assets/iris.jpg > assets/iris.svg

Polygon clipping (Greiner-Hormann)

Source

# build library & example app
make config=release_sse ex-polyclip && bin/release/ex-polyclip > polyclip.svg

Polygon offsetting

Source

# build library & example app
make config=release_sse ex-polyclip && bin/release/ex-polyoffset > polyoffset.svg

Verlet physics

Source | Video example 1 | Video example 2

# build library & example app
make config=release_sse ex-verlet && bin/release/ex-verlet

# ouputs are stored as SVG sequence in /assets
# use script below to convert to mp4 (requires rsvg & ffmpeg) -> out.mp4
./makevideo verlet

Voronoi

Source

# build library & example app
make config=release_sse ex-voronoi && bin/release/ex-voronoi

Piping in points from external process

The image above was generated by first sampling a JPG with the poisson example tool (configured to output points as text) and then piping these points into the voronoi example.

bin/release/ex-poisson -b 00ffff -f 0000ff -q 500 -m 2 -x 16 -t assets/iris.jpg | \
bin/release/ex-voronoi -p -w 757 -h 450 > iris-voronoi.svg

Build & test

Get further help for autogenerated Makefile:

# checkout with submodules
git clone --recursive https://github.com/thi-ng/c-thing

# generate Makefiles
premake5 gmake

make help
# Usage: make [config=name] [target]
# CONFIGURATIONS:
#   debug_sse
#   debug_no_sse
#   release_sse
#   release_no_sse
# 
# TARGETS:
#    all (default)
#    clean
#    test
#    test_asan
#    lib
#    ex-ca1d
#    ex-ca2d
#    ex-chull
#    ex-dla
#    ex-poisson
#    ex-verlet
#    ex-verlet-pack
#    ex-polyclip
#    ex-polyoffset
#    ex-voronoi
#    ex-glfw01

# build & run tests manually
make config=debug_sse test && bin/debug/test
# or
make config=release_sse test && bin/release/test

# ...or use auto test w/ file watcher
# tests re-run automatically if files in /src or /test are changed
# if no args given, compiles w/ address sanitizer enabled
./autotest
# ...or provide build config (target config profile)
# (only test_msan requires linux & clang, other profiles also build w/ gcc etc.)
./autotest test_msan
./autotest test_asan debug
./autotest test release no_sse

Build static library

make config=debug_sse lib
# or
make config=release_sse lib

Build source x-ref

brew install cscope

./browse

Disassemble & list symbols

# display disassembly (OSX)
otool -jtV bin/release/libcthing.a | less

# display global symbols defined in lib
nm -g -j bin/release/libcthing.a | grep --color=never _ct_

Compile with emscripten

Build as library for emcc

Also see GLFW example for further details…

# build LLVM bitcode version for future linking with other sources
./compile-bc

Run test suite in browser

# help / usage
./compile -h
# Usage:
#   -a     : separate asm.js output
#   -c     : enable Closure compiler step
#   -d     : remove duplicate functions
#   -D SYM : add define
#   -h     : show this help
#   -k     : enable runtime checks
#   -m     : enable memory checks
#   -s     : enable SSE (SIMD.js)
#   -t     : include tests

# compile with tests, closure pass & remove duplicate fns
./compile -tdc

python3 -m http.server

# in browser dev console - http://localhost:8000/
cthing(); cthing._main()

Build customization

This project utilizes feature macros defined in the thi.ng/ct-head project. Please see documentation there for further reference to customize behavior.

Contributors

Name	Role	Website
Karsten Schmidt	initiator & principal developer	thi.ng

License

This project is open source and licensed under the Apache Software License 2.0.