Home

dlib

dlib is a growing collection of native D language libraries that implement common functionality (read below about our definition of "common"). It is useful for various higher-level projects - such as game engines, rendering pipelines and multimedia applications.

Currently dlib contains the following packages:

• dlib.core - modules that are widely used by other packages
• dlib.memory - allocators and memory management functions
• dlib.container - containers and data structures
• dlib.filesystem - abstract FS interface and its implementations for Windows and POSIX filesystems
• dlib.math - linear algebra and numerical analysis (vectors, matrices, quaternions, etc.)
• dlib.geometry - computational geometry (ray casting, primitives, intersection, etc.)
• dlib.image - image processing (filters, color correction, FFT, HDRI, graphics formats I/O, support for 8 and 16-bit RGBA buffers and floating point operations)
• dlib.audio - sound processing (synthesizers, audio formats I/O)
• dlib.network - networking and web functionality
• dlib.async - event loop and asynchronous programming capabilities
• dlib.serialization - data serialization (currently includes lightweight XML parser)
• dlib.coding - data encryption and compression algorithms
• dlib.text - text processing
• dlib.functional - some functional programming idioms (HOFs, combiners, quantifiers, etc.).

Philosophy behind the project

Why dlib? Read the Rationale.

It is hard to tell exactly what dlib is, but much easier to list what it isn't:

• dlib is not a complete application development framework. It won't include GUI, window management, input handling, etc, because there are already enought mature and useable GUI toolkits;
• dlib is not a "second standard library". We try to keep Phobos dependency low due to our strict memory management policy, but making dlib fully replace the standard library is not our goal;
• dlib is not a game engine. Instead, it provides core functionality for building one;
• dlib is not an experimenting ground. We don't invent new ideas, we only make efficient and useable implementations.

Our general principle is the following: if some concept is well-defined and has time-proven way of implementation, then this concept is considered "common" and could be included to dlib. If, on the contrary, something has no "right way" of doing it, then it considered "not common". In this case everyone should be free to experiment and make their own decisions - dlib will stay away from that.

In short, dlib doesn't force arguable things.

We also adhere the following ideas:

• Our "Holy Trinity" are Performance, Portability and Usage Simplicity. They are more important than everything else;
• No dependencies, third-party libraries, bindings, wrappers, whatsoever. No one likes dependencies. We keep it self-sufficient to make usage, shipping and maintenance easier. dlib only depends on Phobos and system APIs like POSIX and Win32;
• Internal dependency between modules is minimal. If you don't need something (for example, dlib.image, dlib.serialization or dlib.network), you can throw it out;
• dlib's interfaces are platform-independent, while implementations may be not. The general principle is to allow user to write fully cross-platform code, while maintaining all the platform-dependent stuff at the backend;
• dlib avoids dynamic memory allocation where possible. Where not possible, it tries to rely on user for that. Read below about our memory management policy;
• [to be continued...]

Memory Management

A large effort is recently being made to lessen garbage collector usage in dlib. The main policy is to make the user responsible for memory allocation, not the library. All necessary internal allocations must avoid using GC and instead should use dlib.core.memory routines (which are, in turn, based on standard C malloc/free).

This task is almost complete, but there is still a lot of work. The following is a list of modules that support manual memory management:

• dlib.core is fully GC-free
• dlib.container is fully GC-free
• dlib.serialization is fully GC-free
• dlib.functional is fully GC-free
• dlib.coding is fully GC-free
• dlib.text is fully GC-free
• dlib.math originally avoids GC usage, being designed for real-time application purposes (warning: this is not true for Tensors, which can allocate in certain cases. Use carefully)
• dlib.geometry is partially GC-free (full code audit haven't been done yet, use with care)
• dlib.filesystem has GC-free implementations of its interfaces (dlib.filesystem.stdfs)
• dlib.image is partially GC-free (there are UnmanagedImage class and fully GC-free image decoders, all image filters are also GC-free)
• dlib.audio has also GC-free implementation of its generic interfaces.

First-place candidates for memory related improvement are dlib.image (parallel image processing, FFT) and dlib.geometry.

Look Manual Memory Management for more details on dlib.core.memory usage.

Issue tracker

On GitHub issue tracker, we use several labels to mark bugs and improvements:

• Breaking change. This is self-descriptive: an improvement that breaks backward compatibility;
• Bug. A bug that should be fixed without API change;
• Enhancement. A non-breaking improvement of existing functionality (e.g. optimization or a new feature);
• Missing. Appears when existing functionality is removed due to regressions and needs to be rewritten, or when some implementation is not complete;
• New functionality. Self-descriptive: a new functionality request.