gecko0307/dlib

Allocators, I/O streams, math, geometry, image and audio processing for D

dlib is a high-level general purpose library written in D language for game and graphics developers. It provides basic building blocks for writing real-time and multimedia applications: containers, data streams, linear algebra and image decoders.

dlib has no external dependencies aside D's standard library. dlib is created and maintained by Timur Gafarov.

If you like dlib, please support its development on Patreon or Liberapay. You can also make one-time donation via NOWPayments. I appreciate any support. Thanks in advance!

What's inside

Currently dlib consists of the following packages:

• dlib.core - basic functionality used by other modules (memory management, streams, threads, etc.)
• dlib.container - generic data structures (GC-free dynamic and associative arrays and more)
• dlib.filesystem - abstract FS interface and its implementations for Windows and POSIX filesystems
• dlib.math - linear algebra and numerical analysis (vectors, matrices, quaternions, linear system solvers, interpolation functions, etc.)
• dlib.geometry - computational geometry (ray casting, primitives, intersection, etc.)
• dlib.image - image processing (8-bit, 16-bit and 32-bit floating point channels, common filters and convolution kernels, resizing, FFT, HDRI, animation, graphics formats I/O: JPEG, PNG/APNG, BMP, TGA, HDR)
• dlib.audio - sound processing (8 and 16 bits per sample, synthesizers, WAV export and import)
• dlib.network - networking and web functionality
• dlib.memory - memory allocators
• dlib.text - text processing, GC-free strings, Unicode decoding and encoding
• dlib.serialization - data serialization (XML and JSON parsers)
• dlib.random - random number generation
• dlib.coding - various data compression and coding algorithms
• dlib.concurrency - a thread pool.

Supported Compilers

dlib is automatically tested for compatibility with latest releases of DMD and LDC. Older releases formally are not supported, but in practice usually are, to some extent. There's no guaranteed support for GDC and other D compilers.

Documentation

HTML documentation can be generated from source code using ddox (run dub build -b ddox) or Doxygen (run doxygen). Be aware that documentation is currently incomplete.

• Autogenerated documentation
• Wiki
• Rationale
• FAQ
• Best Practices
• Contributing Guidelines
• Gitter chat room

License

Copyright (c) 2011-2024 Timur Gafarov, Martin Cejp, Andrey Penechko, Vadim Lopatin, Nick Papanastasiou, Oleg Baharev, Roman Chistokhodov, Eugene Wissner, Roman Vlasov, Basile Burg, Valeriy Fedotov, Ferhat Kurtulmuş, João Lourenço, Ate Eskola, Aaron Nédélec, Alexander Perfilyev. Distributed under the Boost Software License, Version 1.0 (see accompanying file COPYING or at https://www.boost.org/LICENSE_1_0.txt).

Sponsors

Jan Jurzitza (WebFreak), Daniel Laburthe, Rafał Ziemniewski, Kumar Sookram, Aleksandr Kovalev, Robert Georges, Rais Safiullin (SARFEX), Benas Cernevicius, Koichi Takio, Konstantin Menshikov.

Users

• Dagon - 3D game engine for D
• Electronvolt - work-in-progress first person puzzle game
• DagoBan - Sokoban clone
• DlangUI - native UI toolkit for D
• rengfx - game engine based on raylib
• Voxelman - voxel-based game engine
• RIP - image processing and analysis library by LightHouse Software
• GeneticAlgorithm - genetic algorithms library
• Orb - a game/engine with procedural content
• Leptbag - physics simulator by Gamma-Lab. Written in C++, but supports D plugins
• aoynthesizer - sound synthesizer based on Lisp-like scripting language
• D-VXLMapPreview - isometric preview generator for Ace of Spades and Iceball maps
• SMSFontConverter - a program for generating Sega Master System fonts
• sacengine - engine reimplementation for the game Sacrifice
• Shaders Playground - a sandbox project for experimenting with OpenGL shaders
• wgpu-dlang - WebGPU usage example.

dlib's Issues

Improve JPEG support

• Grayscale JPEG support
• Progressive JPEG support
• Saving to JPEG

Warnings with dmd 2.066-beta3

dlib-master\dlib\math\vector.d(533)
: Warning: calling dlib.math.utils.clamp!ushort.clamp without side effects disca
rds return value of type ushort, prepend a cast(void) if intentional
dlib-master\dlib\image\image.d(86):
 Deprecation: Read-modify-write operations are not allowed for shared variables.
 Use core.atomic.atomicOp!"+="(this.progress, this.pixelCost) instead

Add modulo operator to Vector type

It will be useful to have such syntax:

    chunkWorldPos.x %= REGION_SIZE;
    chunkWorldPos.y %= REGION_SIZE;
    chunkWorldPos.z %= REGION_SIZE;

as

    chunkWorldPos %= REGION_SIZE;

Redesign OpenFile in dlib.core.stream

Here is what I consider suitable. Since what, in principle, OpenFile does is abstracts a filesystem interface, we can do something like this:

interface Filesystem
{
    IOStream open(string fileName, FileMode mode);

    // Probably also remove, rename, mkdir etc.
}

class StdFilesystem: Filesystem
{
    IOStream open(string fileName, FileMode mode)
    {
        return new FileStream(new std.stream.File(fileName, mode));
    }

    // ...
}

StdFilesystem stdfs;

static this()
{
    stdfs = new StdFilesystem();
}

IOStream openFile(string fileName, FileMode mode = FileMode.In)
{
    return stdfs.open(fileName, mode);
}

The main question is, what methods do we need in an interface like that?

dlib.image.hdri won't compile with DMD 2.065

Still can't find the reason.

Implement missing methods in StdFileSystem

These are openForIO, openDir, createDir, remove.

Special case inversion for affine 4x4 matrices

Using inverseAffine doesn't always guarantee identity as a result of M * M^-1. Need rewriting.

Cannot compile ~master using dub and dmd v2.064

dlib-master$ dub build
Checking dependencies in '/home/dlib-0.3.0'
Package dlib (configuration "library") defines no import paths, use {"importPaths":   [...]} or the default package directory structure to fix this.
Building configuration "library", build type debug
Running dmd...
dlib/xml/lexer.d(187): Error: function dlib.xml.lexer.Lexer.getForward (ulong position, int num) is not callable using argument types (ulong, ulong)
dlib/geometry/obb.d(53): Error: no property 'translation' for type 'Matrix!(float, 4)'
dlib/geometry/obb.d(59): Error: no property 'translation' for type 'Matrix!(float, 4)'
dlib/geometry/intersection.d(128): Error: incompatible types for ((dot) * (dir)): 'float' and 'Vector!(float, 3)'
dlib/geometry/intersection.d(212): Error: no property 'translation' for type 'Matrix!(float, 4)'
dlib/geometry/intersection.d(242): Deprecation: function dlib.math.matrix.Matrix!(float, 4).Matrix.transform is deprecated - Matrix!(T,N).transform is deprecated, use vector to matrix multiplication instead
dlib/image/io/png.d(364): Error: function dlib.math.utils.networkByteOrder (uint value) is not callable using argument types (ulong)
dlib/image/io/png.d(442): Error: cannot implicitly convert expression (tmp.length) of type ulong to uint
dlib/image/io/zstream.d(46): Error: cannot implicitly convert expression (dest.length) of type ulong to uint
dlib/image/io/zstream.d(47): Error: cannot implicitly convert expression (dest.length) of type ulong to uint
dlib/image/io/zstream.d(61): Error: cannot implicitly convert expression (input.length) of type ulong to uint
dlib/image/io/zstream.d(94): Error: cannot implicitly convert expression (this.dest.length / 2LU) of type ulong to uint
dlib/math/fft.d(52): Error: cannot implicitly convert expression (data.length) of type ulong to uint
Error: DMD compile run failed with exit code 1

Compiler error: incorrect import for dlib.core.image

Changing line 42 in /dlib/image/package.d to import dlib.core.image; fixes compilation for now.

The compiler error is as below:

 /dlib-master/dlib/image/package.d(42): Error: module dlib.core.image from file ../../../.dub/packages/dlib-master/dlib/image/unmanaged.d must be imported with 'import dlib.core.image;'

There is clamp function in newest phobos

If it is possible to detect if clamp is presented with something like __traits(compiles, ...), or by checking compiler version you can make public import of clamp from phobos, or present your own function.

nextPowerOfTwo is giving wrong result on uint

assert( nextPowerOfTwo!uint(2500) == 4096 ); // returns 4092

Support more subsampling modes in JPEG decoder

Such as 4:4:4, 4:4:0, 4:2:2, 4:1:1, 4:1:0.

SIMD in Vector, Matrix

(following the previous conversation...)
I also believe we should pay extra attention to leave our back door open for a possible SIMD implementation in the future. The way I imagine it, as SIMD isn't practical everywhere, would be through another template parameter. An example probably illustrates it better:

vec4 doWhatever(const ref vec4 data, const ref mat4 matrix) {
    // convert to SIMD types
    vec4sse data_simd = data;     // alias for Vector!(4, float, Vector.SSE)
    mat4sse matrix_simd = matrix;    // Matrix!(4, float, Vector.SSE)

    // now do some really complex and expensive operation
    ...

    // convert back to plain ol' floats and return
    return data_simd;
}

GC-free XML parser

dlib.xml package should be rewritten with manual memory management.

Doesn't build

DMD64 D Compiler v2.068.0
dlib - 0.6.2
Linux

/dlib/filesystem/stdfs.d(73): Error: function core.stdc.stdio.fseek (shared(_IO_FILE)* stream, long offset, int whence) is not callable using argument types (shared(_IO_FILE)*, fpos_t, int)
/dlib/math/vector.d(525): Warning: int *= float is performing truncating conversion
/dlib/math/vector.d(525): Warning: uint *= float is performing truncating conversion
/dlib/math/vector.d(525): Warning: int *= float is performing truncating conversion
/dlib/math/vector.d(525): Warning: uint *= float is performing truncating conversion
/dlib/math/vector.d(525): Warning: int *= float is performing truncating conversion
/dlib/math/vector.d(525): Warning: uint *= float is performing truncating conversion
/dlib/math/vector.d(525): Warning: ushort *= float is performing truncating conversion

unittest build failed

travis-ci unittest build for my project dlangide fails on dlib:

Building dlib 0.4.1 configuration "library", build type unittest.
Running dmd...
../../../.dub/packages/dlib-0.4.1/dlib/filesystem/local.d(341): Error: function dlib.filesystem.local.findFiles (string baseDir, bool recursive) is not callable using argument types (ReadOnlyFileSystem, string, bool)
../../../.dub/packages/dlib-0.4.1/dlib/filesystem/local.d(361): Error: undefined identifier 'functions'
../../../.dub/packages/dlib-0.4.1/dlib/filesystem/local.d(363): Error: undefined identifier 'functions'
../../../.dub/packages/dlib-0.4.1/dlib/math/vector.d(948): Warning: calling dlib.math.vector.Vector!(float, 3).Vector.length without side effects discards return value of type float, prepend a cast(void) if intentional
../../../.dub/packages/dlib-0.4.1/dlib/math/vector.d(949): Warning: calling dlib.math.vector.Vector!(float, 3).Vector.lengthsqr without side effects discards return value of type float, prepend a cast(void) if intentional
../../../.dub/packages/dlib-0.4.1/dlib/math/vector.d(950): Warning: calling dlib.math.vector.distance!float.distance without side effects discards return value of type float, prepend a cast(void) if intentional
FAIL ../../../.dub/packages/dlib-0.4.1/.dub/build/library-unittest-linux.posix-x86_64-dmd_2066-C3294255E83FD63DEF449B07C61958D9/ dlib staticLibrary
Error executing command test: dmd failed with exit code 1.

FileSystem should support both '/' and '\' as path separators

AFAIK, Posix requires '/' and Winapi requires ''. Are there standard functions to do the conversion?

Recent tags don't match semVer spec

Latest version of dlib don't have 'v' prefix like v0.3.0, so i can't fetch dlib using dub.

Remove deprecated functionality

Such as identityMatrix, Vector.transform, etc.

Add vec <-> ivec convertion

Would be nice to have an easy way to convert one type to another through constructor.
like ivec3 discretePos = ivec3(vec3var); or maybe with to!ivec3(vec3Var);

Currently I use

ivec3 toivec3(vec3 vec)
{
    return ivec3(cast(int)vec.x, cast(int)vec.y, cast(int)vec.z);
}

Unittests failed

Building dlib 0.5.2 configuration "library", build type unittest.
Running dmd...
../../../.dub/packages/dlib-0.5.2/dlib/filesystem/local.d(342): Error: no property 'filter' for type 'std.range.interfaces.InputRange!(DirEntry)'
FAIL ../../../.dub/packages/dlib-0.5.2/.dub/build/library-unittest-linux.posix-x86_64-dmd_2067-EA65A65E20E3EAC0F371C7F7489485A2/ dlib staticLibrary
Error executing command test:
dmd failed with exit code 1.

Clipping is not working for fillRect in OpenGL drawbuffer

Reimplement old Huffman coding with manual memory management

PNG exporter bug

Currently PNG exportrer writes a single large IDAT chunk with image data. In some cases (when encoding non-compressible images such as pixel art), this gives invalid results at zlib compression stage. RFC 1951 (DEFLATE algorithm spec) states that the block sizes are arbitrary, except that non-compressible blocks are limited to 65,535 bytes. So the exporter should break the data into 64K chunks.

Manual memory management in filters

Image filters should optionally accept preallocated output storage.

Doesn't Build on Mac

dlib/math/sse.d(184): Error: bad type/size of operands 'mov'
FAIL .dub/build/library-debug-posix.osx-x86_64-dmd_2066-5F283B0B6A1DC5388B277615AB841C18/ dlib staticLibrary
Error executing command run: dmd failed with exit code 1.

Truncation in *= warnings

A lot of warnings like
dlib-0.5.3\dlib\math\vector.d(525,35): Warning: int *= float is performing truncating conversion
dlib-0.5.3\dlib\math\vector.d(525,35): Warning: uint *= float is performing truncating conversion

Could you please fix?

Vector.opDispatch doesn't work on const instance

The following code will fail to compile:

import dlib.math.vector;

static this() {
    const ivec3 v = ivec3(1, 2, 3);

    const int x = v.x;
}

This probably applies to other Vector methods, too. I'd gladly provide a patch, but I'm not sure how to solve this without duplicating the whole method.

PNG and JPEG loaders are not freeing memory on decoding error

They should use SuperImage.free to ensure that underlying SuperImage implementation correctly releases its memory.

lanczos and bicubic resampling don't work

WAV export in dlib.audio

Filed to build unittest configuration under x64 compiler

lve@vlopatin-laptop:~/src/d/dlib$ dub build --build=unittest
Building dlib 0.4.1+commit.34.gebd7d7c configuration "library", build type unittest.
Running dmd...
dlib/core/oop.d(174): Warning: use '{ }' for an empty statement, not a ';'
dlib/core/oop.d(180): Warning: use '{ }' for an empty statement, not a ';'
dlib/core/oop.d(185): Warning: use '{ }' for an empty statement, not a ';'
dlib/container/array.d(70): Error: None of the overloads of 'append' are callable using argument types (int), candidates are:
dlib/container/array.d(89): dlib.container.array.DynamicArray!(HuffmanTableEntry, 32LU).DynamicArray.append(HuffmanTableEntry c)
dlib/container/array.d(118): dlib.container.array.DynamicArray!(HuffmanTableEntry, 32LU).DynamicArray.append(const(HuffmanTableEntry)[] s)
dlib/container/array.d(85): Error: cannot implicitly convert expression (0) of type int to HuffmanTableEntry
dlib/image/io/jpeg.d(153): Error: template instance dlib.container.array.DynamicArray!(HuffmanTableEntry, 32LU) error instantiating
FAIL .dub/build/library-unittest-linux.posix-x86_64-dmd_2066-2961EB2D0079E9BB12186E96CBA5D5F0/ dlib staticLibrary
Error executing command build: dmd failed with exit code 1.

Compilation errors in unit test mode

Upon building an application using Dlib for unit test (e.g. dub --build=unittest), the compilation fails with following errors:

..\..\..\dlib\dlib\core\bst.d(110): Error: Cannot modify 'this'
..\..\..\dlib\dlib\core\bst.d(115): Error: Cannot modify 'this'
..\..\..\dlib\dlib\core\aarray.d(72): Error: template instance dlib.core.aarray.AArray!string error instantiating
..\..\..\dlib\dlib\functional\combinators.d(76): Error: no property 'filter' for type 'int[]'
..\..\..\dlib\dlib\functional\combinators.d(78): Error: no property 'filter' for type 'int[]'
Error executing command run: DMD compile run failed with exit code 1

Am I missing something or are these actual errors in the code?

Reimplement dlib.image.io with streams

Stream-based image I/O would bring compatibility with virtual filesystems and networking.

iota is not in std.algorithm

In commit 915597e, import std.functional; was changed to import std.algorithm : iota, reduce;.

However, std.algorithm does not contain an iota function in DMD v2.067.1.

DMD compiler output:

dlib\math\combinatorics.d(11): Error: module std.algorithm import 'iota' not found

Rewrite Matrix with column-major order

...to gain better compatibility with OpenGL and address multiplication-related issues mentioned in #14.

Request: Implement frustum and frustum intersections

Implement frustum: just Plane[6] planes;.
Implement frustum construction. From projection/perspective matrix for example.
Implement frustum AABB intersection test.
Plane extraction
Frustum - AABB Intersection implementation

Implement the most efficient HashMap in the world

We don't seem to have one, or is my eyesight getting bad?

64bit build is broken

Using Ubuntu x64:

Building dlib ~master configuration "library", build type debug.
Running dmd...
../../../.dub/packages/dlib-master/dlib/image/io/zlib.d(81): Error: function dlib.image.io.zlib.ZlibEncoder.reallocateBuffer (uint len) is not callable using argument types (ulong)
../../../.dub/packages/dlib-master/dlib/image/io/zlib.d(91): Error: function dlib.image.io.zlib.ZlibEncoder.reallocateBuffer (uint len) is not callable using argument types (ulong)
../../../.dub/packages/dlib-master/dlib/image/io/zlib.d(157): Error: function dlib.image.io.zlib.ZlibDecoder.reallocateBuffer (uint len) is not callable using argument types (ulong)
../../../.dub/packages/dlib-master/dlib/image/io/zlib.d(167): Error: function dlib.image.io.zlib.ZlibDecoder.reallocateBuffer (uint len) is not callable using argument types (ulong)
FAIL ../../../.dub/packages/dlib-master/.dub/build/library-debug-linux.posix-x86_64-dmd_2067-3DFF75C58537CAA01A8A2A997801CE14/ dlib staticLibrary
Error executing command run: dmd failed with exit code 1.

Indexed PNG's won't load

I guess the problem is in the filtering code.

Publishing DDoc documentation

dub --build=docs generates DDoc documentation.
Most modules are not documented right now, but for those few that are it would be nice to be able to publish the documentation online. Can we do this with just github? Just pushing these to the repo will display them as HTML source code.

Reimplement functions in dlib.math.affine

#16 is fixed, but most of the functions in dlib.math.affine are still missing. I rewrote only widely-used ones to make the module pass the unittest. Missing functions are marked as TODO.

To make porting process easier, old implementations are still there (matrix_old.d, affine_old.d).

Generic matrix inversion should use LU decomposition

According to my tests, inversion via LU decomposition is 4 times faster than current analytic method.

Image convolution doesn't work correctly

Rewrite all image loaders with manual memory allocation

Image loaders now use much of GC, which is no good. I'm going to use the following workaround (already implemented in PNG loader):

• Actual image data allocation should be abstract (by using SuperImageFactory interface in dlib.image.image). Thus one can choose between manual and GC-based allocation
• Temporary data used by loaders should be allocated in unmanaged heap (using dlib.core.memory routines).

Normals of frustum's planes are pointing inside frustum

I found that plane normals of frustum are pointing inside frustum, while common solution is to make them point outside. Maybe it will be better to make them point outside to minimize confusion?

Coordinates clamping on image data access

It should be done only in getPixel, and not in setPixel.

Clean dlib.core

All container implementations from dlib.core (aarray, bst, hash, linkedlist, queue, stack) should be moved to new package dlib.container.

Dlib fails to compile as a dub dependency

I added dlib as a dependency to my dub-based project, but when trying to build it, I'm getting these errors:

Package dlib (configuration "library") defines no import paths, use {"importPaths": [...]} or the default package directory structure to fix this.
...
../../../.dub/packages/dlib-0.2.4/dlib/image/package.d(45): Error: module morphology is in file 'dlib/image/filters/morphology.d' which cannot be read

I tried to manually modify dlib's package.json, adding '.' as an importPath, but that gives me errors like:
dlib/image/package.d(45): Error: module dlib.image.morphology from file ... must be imported as module 'dlib.image.morphology'

Unnecessary vertical flipping in PNG importer and exporter

Don't know whether it appeared there on memory-related refactoring or was from the very beginning.