1. moka NA
  2. Motor

Overview

HTTPS SSH

Motor Libraries

Motor is a collection of modular C++ libraries for multimedia purposes. Inter-library dependencies are minimized to keep each package as a manageable and testable unit while allowing users to only link against the libraries that actually contain the functionality they need for their project. Motor cleanly separates API and implementation to avoid bloated header files and allow for clean documentation. It is designed as a thread aware framework that makes use of multithreading where it makes sense. Motor contains functionality for resource management from local filesystem and HTTP, a networking library, an object oriented render system for GPU drawing, an application library for windowing and input, libraries for audio, video and imaging among others.


Platforms

Motor has been developed on OSX. At this point OSX 10.9 and upwards are the only fully supported Platforms. Motor has been designed with portability in mind. Please see the porting guide at the end of this document for more information.


Overview

Dependency Tree

Dependency Tree

MotorCore

  • Platform detection
  • Byte order utilities
  • Threading
  • String utilities
  • Unicode utilities
  • URI utilities
  • Events
  • Error handling API
  • Time utilities
  • Logging utilities etc.

MotorMath

  • 2D & 3D Vector, Quaternion, Matrix Math
  • Color operations
  • Random numbers
  • Noise
  • FFT
  • Window functions
  • Splines
  • Tweens
  • Rectangle, Circle, Line math etc.

MotorMathLua

  • Work in progress lua binding of MotorMath.

MotorPropertyTree

  • Generic in-memory Property Tree representation
  • Loads and exports JSON and XML

MotorFileSystem

  • Directory iterators
  • Create, modify and delete files, symbolic links and directories.

MotorNetworking

  • TCP and UDP sockets and stream buffers
  • simple HTTP client
  • IP4 and IP6 support

MotorResource

  • Extensible and generic Resource managment
  • loads resources from local file system and HTTP
  • save resources
  • save and load resources non-blocking (asynchronous)
  • makes sure each resource exists in memory only once
  • event driven

MotorImage

  • generic in-memory representation of 2D and 3D images
  • API to iterate and access individual pixels and channels in an intuitive way
  • due to its generic nature custom image representations (i.e. internal data type and channel layout) are usually just a matter of creating a new typedef
  • RTTI mechanics to easily determine the type (internal data type and channel layout) of a generic image at runtime
  • load an save images.

MotorRenderSystem

  • object oriented API for hardware accelerated GPU drawing
  • Vertex and Index Buffer API to upload Geometry to the GPU
  • Flexible Texture API
  • Renderbuffer API (for offscreen rendering)
  • GPUProgram API (for shader programing)
  • Hardware Instancing
  • SimpleRenderer for easy drawing of simple primitives and immediate mode emulation (as known from oldschool opengl). The immediate mode also allows you to generate static geometry (i.e. geometry generation can be decoupled from drawing) etc.

MotorApplication

  • Windowing
  • Application event loop
  • Display managment
  • Timed callbacks
  • Mouse and Keyboard input
  • event driven

MotorText

  • Generate bitmap fonts from installed system fonts or file (i.e. ttf)
  • Save and load Bitmap fonts in custom JSON based format
  • Unicode aware
  • Advanced text layouting supporting ligatures etc.
  • Fast texture based rendering, easily customizable.

MotorMedia

  • Play Audio from in-memory buffer or sound file
  • Stream Audio
  • Stream Video
  • Record Audio
  • Convert Audio
  • Record Video (optionally with audio)
  • event driven

MotorGlua

MotorPaper

  • The Swiss Army Knife of Vector Graphics at native speed.
  • Powerful document object model based vector graphics API base on paper.js (http://www.paperjs.org)
  • Custom & very fast hardware accelerated rendering backend to rasterize the vector graphics.
  • Rendering backend is fully decoupled from everythin else & can be easily replaced.

MotorPaperLua

  • Work in progress lua binding of MotorPaper.

MotorMIDI

  • MIDI device management
  • MIDI input (output is still missing, this is an alpha, ok? :D)

MotorBasicResources

  • Implements resource types that can be managed throgh the ResourceManager in MotorResource for basic motor types such as PropertyTrees and Images.

Installation & Project Generator

Motor lives in its own Motor directory and does not copy or install files anywhere else. You can put it in any place on your drive.

Motor uses it's own little a python based command line tool that interprets simple build scripts to generate Xcode (and in the future different) Project files called ProjectGenerator, which lives in a seperate repository.

To install Motor, you should download ProjectGenerator and follow its installation instructions. After doing so, installing Motor is a simple two step process. First you call

./Configure.py inside the Motor directory to initialize some environment variables that point to the MotorProjectCreator (see next section) commandline tool.

To generate all the Projects for the Motor libraries and examples, enter the Buildfiles directory

cd Buildfiles

and call the PGen command to run the ProjectGenerator script that creates all the Projects.

PGen

That's it!


Motor Project Creator

MotorProjectCreator is a motor specific commandline tool built on top of ProjectGenerator. It allows you to create new motor projects based on different presets from the commandline by simply letting it know which preset to use and what motor libraries to link agains. The script resolves all the native dependencies internally. It generates and runs PGScript.py ProjectGenerator script in the folder you call the command from which actually generates the Project files.

Motor currently ships with two presets, one for WindowedApp, which creates a project for windowed application development and therefore links agains MotorApplication and one for ConsoleApp which only links against MotorCore by default. On OSX WindowedApp creates an application bundle, while ConsoleApp only creates an executable. If no preset is explicitly defined, WindowedApp is the default.

The syntax is as follows:

MotorCreateProject --name MyProjectNyme --type ConsoleApp or WindowedApp --links LibA LibB LibC

For example if you want to create a Project called AwesomeConsoleProject that is a ConsoleApp and links agains MotorFileSystem and MotorNetworking, you would do the following:

MotorCreateProject --name AwesomeConsoleProject --type ConsoleApp --links MotorFileSystem, MotorNetworking

Having this infrastructure in place allows Motor to only have the small python ProjectGenerator scripts in the repository instead of the rather big .xcodeproj (or other project files in the future for that matter).


Todo list

General

  • add a Serial library that works similar to the existing Socket API in Motor
  • Come up with a plan to do the lua bindings for the individual motor libraries (i.e. some conventions if overloaded functions should be used/allowed etc.)
  • Which libraries should get bindings first?
  • Does anything in MotorGlua have to change to make these binding happen?

MotorMath

  • Finish tween classes (mainly easing functions etc.)
  • Finish Reference
  • Replace the numeric solvers (used for bezier class) with the most recent implementations from paper.js
  • more examples
  • Add WorleyNoise (Veronoi Noise)
  • triangulation?
  • add color free functions such as mix etc.
  • unit tests

MotorText

  • Finish Reference
  • Add API to grab font outlines (i.e. to triangulate text)
  • Add support for distance field font rendering (i.e. the valve approach. This should be fairly easy as you should be able to build that on top of the existing bitmap font API)

MotorApplication

  • Finish Reference
  • Add File Dialog API and implementation
  • Add Context Menu API and implementation

MotorMedia

  • Finish Reference

MotorRenderSystem

  • Finish Reference
  • Add API and OpenGL implementation for Tesselation GPU stages
  • Add API and OpenGL implementation for Render to Vertex Buffer (Transform Feedback)
  • Add API and OpenGL implementation for Texture buffers
  • Add proper support and API for Multisampled Textures (check whats missing in the current API in that regard)
  • Add support to read/save GPU state, so you can easily return to a previous state.
  • Add a pixel buffer abstraction? Or encapsulate async texture loading into the texture api direclty?
  • Think if it makes sense at this point to abstract sampler state for textures (i.e Sampler Object in modern opengl)
  • Add simpler overloads to grab pixels / take a screenshot

MotorGlua

  • Finish Reference
  • More examples

MotorPaper

  • Finish Reference
  • Add support for transparency/blending (this is only trivial for the simple alpha blending case)
  • Add SVG import
  • Add support for gradients
  • Add support for path intersections
  • Add support for boolean operations
  • More examples

MotorMIDI

  • Add Reference
  • Add support for MIDI output
  • Add examples

Roadmap

General

  • add a Serial library that works similar to the existing Socket API in Motor.
  • Come up with a consistent API for the lua bindings and create tem.
  • Linux port (high priority)
  • IOS port (low priority, should be little work though)

MotorText

  • Add API to grab font outlines (i.e. to triangulate text)
  • Add support for distance field font rendering (i.e. the valve approach. This should be fairly easy as you should be able to build that on top of the existing bitmap font API)

MotorApplication

  • Add File Dialog API and implementation
  • Add Context Menu API and implementation

What else?


Porting Guide

Motor uses c++11 features where it makes sense, so the target platfrom needs to have a compiler that supports c++11. Motor has been built with a strict seperation of API and implementation. This circumnstance and it's modular nature should make porting pretty straight forward as you can port it library by library, without having to make it compile as a whole.

The libraries which need platform specific implementations are the following:

  • MotorFileSystem (the current implementation is POSIX based, so it most likely will only need a port for Windows)
  • MotorNetworking (the current implementation is BSD Socket based, so again, it will most likely only need a port for Windows and some minor adjustments otherwise)
  • MotorRenderSystem (needs an OpenGL ES implementation for a potential IOS port, needs some platform specific opengl header adjustments)
  • MotorAppication (needs an implementation for opening windows/rendering contexts and grabbing the native input events etc. for the target platform)
  • MotorText (needs implementation for loading a Font from file and system fonts aswell as a way of drawing characters to an image buffer for bitmap font generation)
  • MotorMedia (needs implementation for native audio file parsind and saving, getting audio & vide input, streaming)
  • MotorMIDI (usues CoreMIDI on OSX, needs to use something else on other platforms)

All the other Motor libraries should compile out of the box as they don't depend on any platform specific behaviour or API.


License

Motor is distributed under the MIT license. See attached LICENSE.txt.