Providing Type-Safe Read/Write File Access to
the Full Blender DNA in Java
(open source and free)
Java .Blend provides an object-oriented type-safe Java API to read and/or write data in Blender's .blend files. The API reflects all data types and structures of a .blend file, and thereby provides access to literally every single bit of data. This comes at the cost, that each Java .Blend library can only be used with a specific Blender version. Low-level access happens fully transparent - no need for data lookup, byte ordering or conversion between native types. The API provides a high level of freedom but demands some in-depth knowledge of Blender's source code, too. The basics of Blender's data model are explained in the documentation and the example applications will help to get started.
Java .Blend Library
These libraries contain the Java .Blend APIs for given Blender program release versions in the most recent patch version (e.g. 2.90.1 for 2.90 release).
Downloads will have a suffix like DNA-2.90.8, showing the Blender file version supported. Blender file version and Blender program version can differ in the least significant version number (patch version number). Since Blender version 2.80, you have to have the exact matching library version to read a given blender file. Check Blender's splash screen or execute
blender -v when in doubt about your exact Blender version.
If you need support for a Blender version not mentioned below, refer to Section Generating Data Model and Utilities in the documentation or contact me.
Java .Blend Viewer is an example application which demonstrates reading of a simple scene from a blender file. It also contains examples for writing blend files.
Java .Blend File Viewer is an application which lets you view or debug the data in a .blend file.
Java .Blend SDK
This package contains the source code of the code generator and utilities library. The code generator is used to generate a Java.Blend API for a certain range of Blender versions.
Java .Blend's Source Code Documentation
Source code documentation for generated facade classes is based on extracts from blender source code of each version with minor additions by me. Contributions are welcome (see github link).
- [1.3.4][28/11/2020]: Blender 2.91.0 (Blender file version: 2.91.10)
- Blender version update
- Lots of changes to DNA (see doc/CHANGES_DNA.txt).
- New scalar type 'uchar'.
- Now validating support of all data types from DNA before generating sources.
- [1.3.3][10/10/2020]: Blender 2.90.1 (Blender file version: 2.90.8)
- Blender version update
- No changes to DNA.
- Differentiation between blender version and blender file version.
- [1.3.2][05/09/2020]: Blender 2.90.0 (Blender file version: 2.90.8)
- Blender version update
- Added ID_SIM (block id for simulation data).
- [1.3.1][18/07/2020]: Blender 2.83.2 and Bugfix
- Blender version update
- Updated comment on compatibility of blender files according to recent changes.
- Bugfix by Alex Foster: C pointer arithmetics did not apply increment multiplier in CPointer and CPointerMutable.
- [1.3.0][20/06/2020]: Blender release 2.83
- BlockCodes: Added new block codes for new Blender types hair, point cloud and volume.
- FileVersionInfo: Minversion encapsulated in Version object, similar to Version.
- MainLibBase: Added string representations of supported version range.
- [1.2.0][15/02/2020]: Checked Blender release 2.82
- No changes to Java .Blend SDK source code.
- [1.2.0][24/01/2020]: Checked Blender release 2.81a
- There were no changes to source code: Just checked if 2.81a is still compliant with the existing 2.81-16 DNA lib.
- [1.2.0][30/11/2019]: Refactoring and new API for Blender release 2.81.
- mod: refactored package structure to allow removal of packages doc and generator from DNA lib releases.
- env: finished move to git with github mirror
- [1.1.2-r1446][16/08/2019]: Changes for Blender 2.80.
- add: added new block codes
- [1.1.1-r1271][20/10/2017]: adjusted scripts to generate DNA lib for Blender 2.79.
- add: javadoc packages
- fix: wrong path for java.blend docs
- fix: crash in type cast when parameter is null
- add: copy constructor for all generated facade classes
- mod: set methods accept argument null interpreting it as NULL pointer
- mod: get methods of pointers return null if the C pointer refers to NULL
- [1.1.0-r1117][12/11/2016]: fixed bugs due to overlapping blocks since 2.76 and even more source code documentation
- Added support for offheap areas (see documentation).
- Fixed issue with TreeStoreElem (since 2.76) due to overlapping address areas in blocks (offheap).
- Added tools to extract source code documentation from blender source code using doxygen.
- [1.0.4-r759][18/01/2016]: clarified versioning and conversion between DNA versions
- Added compatibility check.
- Added more details on necessary semantic conversion between DNA versions in documentation.
- [1.0.3-r755][18/01/2016]: fixed build issue
- Fixed missing sdna image.
- [1.0.2-r738][10/01/2016]: minor improvement
- Added static method to check file before instantiating MainLib.
- [1.0.1-r718][06/01/2016]: minor hotfix
- Added missing metainf in jar.
- Fixed issue with unicode on windows.
- Fixed issue with reading of file version specifiers in newer Blender versions.
- [1.0.0-r702][04/01/2016]: 1st release.
- Added licenses for all packages.
- Added documentation with an introduction to Blender DNA, Java .Blend's system specification and a getting started guide.
- Moved documentation files for generated classes in a separate project.
- Reorganised the website.
- Finished Java .Blend's own source code documentation.
- Finished utilities package with MainLib and Factory class.
- Added example to write a .blend file compatible with Blender's clipboard functionality.
- Added example to convert a .blend file into a JSON representation.
- Fixed remaining bugs.
- [0.0.2][r658]: Second tech. demo comprising all specified features
- Refactored the hell out of it!
- Fixed several bugs
- Improved source code documentation all over the place
- Added support for Blender version compatibility checks against data model version
- Introduced Blender file write access
- Introduced Blender file creation and initialisation (with StructDNA and FileGlobal)
- Added creation of StructDNA to support initialisation of .blend files.
- Added Blender factory class supporting allocation of blocks and implicit assignment to facades
- Made generation of Blender version specific utilities optional, since those are not fully generic.
- Introduced allocator to manage virtual addresses of a block table for block allocation
- Introduced documentation system to provide more information to generated classes
- Added script to extract documentation from Blender python api
- Documentation system considers file version to retrieve appropriate version of available documentation
- Added several methods to convert between strings, arrays, pointers considering null termination and charsets.
- Added conversion of pointers or array facades to Java native scalar type arrays
- Introduced iterators for arrays
- Optimised bulk data retrieval
- Improved runtime adaption to architecture dependent encoding (byte order and address width)
- [0.0.1][r617]: First demo of model generation and data reading capabilities
- add: Facade concept for structured C types
- add: Abstraction for C pointers and arrays
- add: data model generation from StructDNA
- add: runtime conversion between Java and native data representations
- mod: demo application (cube.blend)
Java .Blend SDK
Java .Blend SDK is published under the terms of the Apache License V2.0.
Java .Blend's DNA Documentation
Java .Blend's DNA Documentation is licensed under GPLv3.
Pregenerated Data Model Packages
Binary packages are licensed under Apache License V2.0.
Source code packages contain documentation of Java .Blend's DNA documentation, and therefore licensed under GPLv3.
Reasons and Effects of the Different Licenses
The reason for the different licensing is, that parts of the documentation are copied from Blender source code and Blender is published under GPLv2. Thus, the documentation is derived work and has to respect the terms of Blender's license.
The different licenses mainly affect redistribution of work based on the documentation files. This means, if someone redistributes work which includes the original or modified documentation files or source code which contains parts of the documentation files (such as comments in generated facade classes), then this work has to respect the terms of the GPLv3.
Thus, if you consider redistributing derived work under a different license compatible with the Apache license of the SDK, than you just need to generate facade classes without Javadoc comments. Refer to Section Generating Data Model and Utilities in Java .Blend's documentation in order to learn how to do this.
If there are still licensing issues that can't be handled that way, than feel free to contact me and I'll try to help find a solution - even if I really hate this topic!