by Rama Karl (c) 2023. MIT license
Libmin stands for minimal utility library for computer graphics. Libmin combines multiple useful functions into a single direct-compile framework with no external dependencies.
Projects with BSD and MIT Licenses have been merged into libmin. The full library is MIT Licensed.
The functionality in Libmin includes:
- Vectors, 4x4 Matrices, Cameras (vec.h, camera.h)
- Quaternions (quaternion.h)
- Stateful Mersenee Twister RNG (mersenne.h)
- Event system (event.h, event_system.h)
- Network system, real-time non-blocking, event-based (network_system.h)
- Drawing in 2D/3D in OpenGL core profile (gxlib)
- 2D GUI Interface library (g2lib)
- Smart memory pointers for CPU/GPU via OpenGL/CUDA (dataptr.h)
- Image class. Multiple image loaders for png, tga, tif. (imagex.h)
- Mesh class. Handles large meshes, loads obj, also suppots .mtl files. (meshx.h)
- Font rendering, using a texture atlas.
- Directory listings (directory.h)
- Http connections (httlib.h)
- Time library, with nanosecond accuracy over millenia (timex.h)
- just_math - Collection of pure math demos for computer graphics
- flightsim - A simple, Single-Body Flight Simulator (SBFM)
- flock2 - A Model for Orientation-based Social Flocking
- logrip - Defend against AI crawlers & botgs with server log analysis
- ProjectiveDisplacement - Projective Displacement Mapping for Raytraced Editable Surfaes
- SHAPES - A lightweight, node-based renderer for dynamic and natural systems
- invk - An Inverse Kinematics Library using Quaternions
Libmin is not built directly.
To build an application, place the app and Libmin repo as sibling folders.
\codes ├── \application └── \libmin
The application has a Cmake that bootstraps and requests Libmin to help with direct-compiled code, third party libs, build and linkage. Before 2024, Libmin was a static/shared library and can be reconfigured as such, yet the new design builds code files directly into your application.
For a simple, complete example see Flock2 cmake: https://github.com/ramakarl/Flock2/blob/main/CMakeLists.txt
See also just_math, as all samples there use Libmin.
Libmin was designed as a versatile, non-intrusive library to provide cross-platform mains, support code, libraries and wrappers for applications that range from interactive OpenGL apps, to GPU-based CUDA apps, to console-based networking apps.
To support many application types non-intrusively, static/shared libraries were found to be insufficient as they make too many assumptions regarding what is necessary to include and leading to bloated shared libs and difficulty versioning across many apps. The primary reasons for static/shared libraries is to provide a feature barrier and to support many applications without duplicating compilation. Libmin is open source and lightweight enough that both are unnecessary and add complexity. Direct code compilation is simpler, allows for selective inclusion, is faster to compile, and is easier to debug. Yet how to provide code modularity with direct inclusion? Optional convenience macros solve this. Macro functions take care of code inclusions (vec, image, mesh, network), of additional libs (OpenGL, OpenSSL, CUDA, FFTW), of linkage (_LINK), and install steps (install_files, install_ptx). Think of Libmin as Cmake the way you wanted it to work.
Applications can follow the typical Cmake workflow. If you include nothing, it is no different that a blank slate C/C++ project built with Cmake. Libmin provides convenience macros that automatically compile & link in additional source code and third party libs. When fully utilized, the result is a simplified project Cmake that simply requests what it needs, links and builds.
An application that uses Libmin create a new CMakeLists.txt and then follows these steps:
- Bootstrap - Create a Cmake that loads the Libmin Bootstrap to find the Libmin packaged cmakes.
- Options - Convenience functions are called to request code include & library linkages [optional].
- Executable - The application executable/library is created as usual using add_executable or add_library.
- Link - The _LINK macro is invoked to simplify linkage [optional].
- Install - Install is done as usual. Additional helper macros install_ptx and install_files are provided to simplify multi-file installs [optional].
These steps follow the usual Cmake workflow and all Libmin steps are optional.
Full use of Libmin provides a convenient way to build in vectors, images, meshes, events, networking, OpenSSL, OpenGL, CUDA, cross-platform mains, etc. for a variety of applications types.
For a simple, complete example see: https://github.com/ramakarl/Flock2/blob/main/CMakeLists.txt
The following is a generalized example:
cmake_minimum_required(VERSION 2.8...3.5)
set (CMAKE_INSTALL_PREFIX ${CMAKE_CURRENT_BINARY_DIR} CACHE PATH "")
set(PROJNAME _your_project_name_)
Project(${PROJNAME})
################
# 1. LIBMIN Bootstrap - this section finds the libmin/cmakes
set ( LIBMIN_ROOT "${CMAKE_CURRENT_SOURCE_DIR}/../../libmin" CACHE STRING "Location of Libmin")
find_package( Libmin QUIET )
..
################
# 2. Options - this section specifies the code & linkage that the application desires
_REQUIRE_DATAPTR()
_REQUIRE_IMAGE()
_REQUIRE_3D()
_REQUIRE_GXLIB()
_REQUIRE_MAIN()
_REQUIRE_GL()
_REQUIRE_GLEW()
..
################
# 3. Executable
file(GLOB MAIN_FILES *.cpp *.c *.h )
_GET_GLOBALS()
add_executable (${PROJNAME} ${MAIN_FILES} ${CUDA_FILES} ${PACKAGE_SOURCE_FILES} ${LIBMIN_FILES})
# 4. Linkage
_LINK ( PROJECT ${PROJNAME} OPT ${LIBS_OPTIMIZED} DEBUG ${LIBS_DEBUG} PLATFORM ${LIBS_PLATFORM} )
..
################
# 5. Install Binary
install ( FILES ${INSTALL_LIST} DESTINATION .) # EXE
Libmin source code, found in this repo, is direct-compiled into an application code.
These are separated by folder in the Libmin repo, and requested using convenience macros:
_REQUIRE_3D - request inclusion of /src/3d folder
_REQUIRE_IMAGE - request inclusion of /src/image folder
_REQUIRE_DATAPTR - request inclusion of /src/dataptr folder
_REQUIRE_G2LIB - request inclusion of /src/g2lib folder
_REQUIRE_GXLIB - request inclusion of /src/gxlib folder
_REQUIRE_NETWORK - request inclusion of /src/network folder
_REQUIRE_MAIN - request linkage to interactive cross-platform main
Libmin provides main wrappers for multiple platforms including Windows, Linux and Android.
Main wrappers are optional. You may write your own main.
A main wrapper is used by calling the _REQUIRE_MAIN() function in your project cmake.
Third party libraries are not included by default.
They are provided on-demand with convenience macros:
_REQUIRE_GL - request linkage to OpenGL lib
_REQUIRE_GLEW - request linkage to GLEW lib
_REQUIRE_JPG - request linkage to libjpg
_REQUIRE_EXT - request linkage to additional libraries bundled in libext
_REQUIRE_OPENSSL(default) - request linkage to libssl-dev
_REQUIRE_BCRYPT(default) - request linkage to bcrypt
_REQUIRE_CUDA(default) - request linkage to NV CUDA, with automatic .cu to PTX compilation
Thanks to:
Mark Zifchock - for early versions of the Android cross-platform pathway
Marcus Pieska - for the OpenSSL stack over the TCP/IP Network layer
Libmin is MIT Licensed with contributions from other BSD and MIT licensed sources.
Individual portions of libmin are listed here with their original licensing.
Copyright listing for Libmin:
Copyright (c) 2007-2022, Quanta Sciences, Rama Hoetzlein. MIT License (image, dataptr, events, gxlib)
Copyright (c) 2017 NVIDIA GVDB, by Rama Hoetzlein. BSD License (camera3d, tga, str_helper, vec, mains)
Copyright (c) 2020 Yuji Hirose. MIT License (httplib.h)
Copyright (c) 2005-2013 Lode Vandevenne. BSD License (LodePNG, file_png)
Copyright (c) 2015-2017 Christian Stigen Larsen. BSD License (mersenne)
Copyright (c) 2002-2012 Nikolaus Gebhardt, Irrlicht Engine. BSD License (quaternion)
Feel free to contact me if you have any questions, comments or suggestions:
Rama Hoetzlein
Website: ramakarl.com
Email: [email protected]