Top Related Projects
DirectXMath is an all inline SIMD C++ linear algebra library for use in games and graphics apps
Bullet Physics SDK: real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc.
Draco is a library for compressing and decompressing 3D geometric meshes and point clouds. It is intended to improve the storage and transmission of 3D graphics.
The DirectX Tool Kit (aka DirectXTK) is a collection of helper classes for writing DirectX 11.x code in C++
Quick Overview
ACL (Animation Compression Library) is an open-source library for compressing and decompressing animation data. It focuses on high compression ratios while maintaining quality and fast decompression, making it suitable for game development and real-time applications.
Pros
- High compression ratios without sacrificing quality
- Fast decompression, optimized for runtime performance
- Cross-platform support (Windows, Linux, macOS, iOS, Android)
- Extensive documentation and integration guides
Cons
- Steep learning curve for advanced usage
- Limited support for non-game development use cases
- Requires careful integration for optimal performance
- May not be suitable for small-scale projects with simple animation needs
Code Examples
- Compressing an animation clip:
#include "acl/compression/compress.h"
acl::compression_settings settings;
settings.level = acl::compression_level8::medium;
acl::compressed_tracks* compressed_tracks = nullptr;
const acl::error_result result = acl::compress_track_list(allocator, track_list, settings, compressed_tracks);
if (result.empty())
{
// Compression succeeded, use compressed_tracks
}
- Decompressing an animation clip:
#include "acl/decompression/decompress.h"
acl::decompression_context<acl::default_transform_decompression_settings> context;
context.initialize(*compressed_tracks);
float sample_time = 1.5f;
acl::transform_output output;
context.seek(sample_time, output);
// Use the decompressed transform in output
- Sampling a specific bone:
#include "acl/decompression/decompress.h"
acl::decompression_context<acl::default_transform_decompression_settings> context;
context.initialize(*compressed_tracks);
uint16_t bone_index = 5;
float sample_time = 2.0f;
acl::transform_output output;
context.decompress_bone(sample_time, bone_index, output);
// Use the decompressed transform for the specific bone
Getting Started
-
Clone the repository:
git clone https://github.com/nfrechette/acl.git
-
Include ACL in your project:
- Add the
includes
directory to your include path - Add the source files from
sources/acl
to your project
- Add the
-
In your code, include the necessary headers:
#include "acl/compression/compress.h" #include "acl/decompression/decompress.h"
-
Use the compression and decompression functions as shown in the code examples above.
Competitor Comparisons
DirectXMath is an all inline SIMD C++ linear algebra library for use in games and graphics apps
Pros of DirectXMath
- Comprehensive library for DirectX development with a wide range of mathematical operations
- Well-documented and maintained by Microsoft, ensuring long-term support
- Optimized for x86 and ARM processors, leveraging SIMD instructions
Cons of DirectXMath
- Primarily focused on DirectX development, limiting its use in other contexts
- May have a steeper learning curve for developers not familiar with DirectX ecosystem
- Less specialized for animation compression compared to ACL
Code Comparison
DirectXMath:
XMVECTOR v1 = XMLoadFloat3(&float3);
XMVECTOR v2 = XMVectorSet(1.0f, 2.0f, 3.0f, 0.0f);
XMVECTOR result = XMVectorAdd(v1, v2);
ACL:
Vector4_32 v1 = vector_load3(&float3);
Vector4_32 v2 = vector_set(1.0f, 2.0f, 3.0f);
Vector4_32 result = vector_add(v1, v2);
Both libraries provide efficient vector operations, but ACL's syntax is more concise and focused on animation-related tasks, while DirectXMath offers a broader range of functions for general DirectX development.
Bullet Physics SDK: real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc.
Pros of Bullet3
- Comprehensive physics simulation library with a wide range of features
- Well-established and widely used in game development and robotics
- Supports both rigid body and soft body dynamics
Cons of Bullet3
- Larger codebase and potentially higher memory footprint
- May have a steeper learning curve for beginners
- Performance can vary depending on the specific use case
Code Comparison
ACL (Animation Compression Library):
ACLCompressor compressor;
CompressedClip compressed_clip;
compressor.compress_clip(clip, compressed_clip);
Bullet3:
btDiscreteDynamicsWorld* dynamicsWorld = new btDiscreteDynamicsWorld(...);
btRigidBody* body = new btRigidBody(mass, motionState, shape);
dynamicsWorld->addRigidBody(body);
Summary
ACL is focused on animation compression, while Bullet3 is a full-featured physics engine. ACL is more specialized and lightweight, potentially offering better performance for animation-specific tasks. Bullet3 provides a broader range of physics simulation capabilities but may be more complex to integrate and use. The choice between the two depends on the specific requirements of your project, with ACL being ideal for animation-heavy applications and Bullet3 better suited for comprehensive physics simulations.
Draco is a library for compressing and decompressing 3D geometric meshes and point clouds. It is intended to improve the storage and transmission of 3D graphics.
Pros of Draco
- Broader compression support: Handles various 3D data types (meshes, point clouds)
- Wider industry adoption and integration in popular 3D tools and engines
- More flexible encoding options for different use cases
Cons of Draco
- Generally larger compressed file sizes compared to ACL for animation data
- Less specialized for animation compression, potentially lower performance for this specific use case
- More complex API and usage for animation-specific tasks
Code Comparison
ACL (Animation Compression Library):
acl::compression_settings settings;
acl::compress_track_list(raw_clip, settings, compressed_clip);
Draco:
draco::Encoder encoder;
encoder.SetAttributeQuantization(draco::GeometryAttribute::POSITION, 10);
draco::EncoderBuffer buffer;
encoder.EncodePointCloudToBuffer(*pc, &buffer);
Summary
Draco offers versatile 3D data compression with wide industry support, while ACL specializes in high-performance animation compression. Draco excels in general 3D asset compression, but ACL may be preferable for projects focused specifically on optimizing animation data size and performance.
The DirectX Tool Kit (aka DirectXTK) is a collection of helper classes for writing DirectX 11.x code in C++
Pros of DirectXTK
- Comprehensive toolkit for DirectX development, offering a wide range of utilities and helpers
- Backed by Microsoft, ensuring long-term support and compatibility with Windows platforms
- Extensive documentation and examples available
Cons of DirectXTK
- Focused solely on DirectX, limiting its use in cross-platform development
- Larger codebase and potentially steeper learning curve compared to ACL
- May include unnecessary features for projects with specific animation compression needs
Code Comparison
ACL (Animation Compression Library):
acl::compression_settings settings;
settings.level = acl::compression_level8::medium;
acl::output_stats stats;
acl::compress_clip(allocator, clip, settings, compressed_clip, stats);
DirectXTK:
auto effect = std::make_unique<BasicEffect>(device);
effect->SetVertexColorEnabled(true);
auto batch = std::make_unique<PrimitiveBatch<VertexPositionColor>>(device);
While ACL focuses on animation compression, DirectXTK provides a broader set of tools for DirectX development. ACL's code is more specialized for animation-related tasks, while DirectXTK offers a wider range of graphics programming utilities.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Animation Compression Library
Animation compression is a fundamental aspect of modern video game engines. Not only is it important to keep the memory footprint down but it is also critical to keep the animation clip sampling performance fast.
The more memory an animation clip consumes, the slower it will be to sample it and extract a character pose at runtime. For these reasons, any game that attempts to push the boundaries of what the hardware can achieve will at some point need to implement some form of animation compression.
While some degree of compression can easily be achieved with simple tricks, achieving high compression ratios, fast decompression, while simultaneously not compromising the accuracy of the resulting compressed animation requires a great deal of care.
Goals
This library has four primary goals:
- Implement state of the art and production ready animation compression algorithms
- Be easy to integrate into modern video game engines
- Serve as a benchmark to compare various techniques against one another
- Document what works and doesn't work
Algorithms are optimized with a focus on (in this particular order):
- Minimizing the compression artifacts in order to reach high cinematographic quality
- Fast decompression on all our supported hardware
- A small memory footprint to lower memory pressure at runtime as well as reducing disk and network usage
Decompression speed will not be sacrificed for a smaller memory footprint nor will accuracy be compromised under any circumstances.
Philosophy
Much thought was put into designing the library for it to be as flexible and powerful as possible. To this end, the following decisions were made:
- The library consists of 100% C++11 header files and is thus easy to integrate in any game engine
- An intermediary clip format is supported in order to facilitate debugging and bug reporting
- All allocations use a game provided allocator
- All asserts use a game provided macro
Supported platforms
- Windows VS2015 x86 and x64
- Windows (VS2017 to VS2022) x86, x64, and ARM64
- Windows (VS2017 to VS2022) with clang x86 and x64
- Linux (gcc 5 to 13) x86 and x64
- Linux (clang 4 to 15) x86 and x64
- OS X (12.5, 13.2, 14.2) x64 and ARM64
- Android (NDK 21) ARMv7-A and ARM64
- iOS (Xcode 10.3, 11.7, 12.5, 13.2, 14.2) ARM64
- Emscripten (1.39.11) WASM
- MSYS2 x64
The above supported platform list is only what is tested every release but if it compiles, it should run just fine.
The Unreal Engine is supported through a plugin found here.
Getting started
This library is 100% headers as such you just need to include them in your own project to start using it. However, if you wish to run the unit tests, regression tests, to contribute to ACL or use it for research, head on over to the getting started section in order to setup your environment and make sure to check out the contributing guidelines.
If you would like to integrate ACL into your own game engine, follow the integration instructions here.
You can install nfrechette-acl
with Conan.
Performance metrics
- Carnegie-Mellon University database performance
- Paragon database performance
- Matinee fight scene performance
- Decompression performance
External dependencies
You don't need anything else to get started: everything is self contained. See here for details.
License, copyright, and code of conduct
This project uses the MIT license.
Copyright (c) 2017 Nicholas Frechette & Animation Compression Library contributors
Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
Contributors â¨
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
Top Related Projects
DirectXMath is an all inline SIMD C++ linear algebra library for use in games and graphics apps
Bullet Physics SDK: real-time collision detection and multi-physics simulation for VR, games, visual effects, robotics, machine learning etc.
Draco is a library for compressing and decompressing 3D geometric meshes and point clouds. It is intended to improve the storage and transmission of 3D graphics.
The DirectX Tool Kit (aka DirectXTK) is a collection of helper classes for writing DirectX 11.x code in C++
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot