cakelab
Home Projects Research Misc. Contact

Java .Blend


Providing Type-Safe Read/Write File Access to

the Full Blender DNA in Java


Version 1.3.10


(open source and free)

github

20-Jan-2023

Holger Machens

About

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.

-homac

Download

Java .Blend Library

Java .Blend APIs for given Blender program LTS releases and the two recent minor releases in their most recent patch version (e.g. 2.93.6 for 2.93 release). LTS releases will be supported for two years, development stages of a running release only until the next minor release comes out.

Downloads have a suffix like DNA-2.90.8, indicating the corresponding Blender file version. Blender file version and Blender program version can differ in its patch version number.

Since Blender version 2.80, you have to have the exact matching Java.Blend API 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.

Mirror on github

Blender Release
3.04 binary src javadoc
3.03 binary src javadoc
3.00 binary src javadoc
2.93 binary src javadoc

Examples

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.

github

version
1.3.10 binary src
1.2.0 binary src
1.1.2 binary src
1.0.4 binary src

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).

Link: github

Change Log

  • [1.3.10][20/01/2023]: Blender 3.3.3 and 2.93.14
    • Both just version bumps for us - no changes to DNA.
  • [1.3.10][03/01/2023]: Blender 3.4.1 and 2.93.13
    • Both just version bumps for us - no changes to DNA.
  • [1.3.10][11/12/2022]: Blender 3.4.0
  • [1.3.10][11/12/2022]: Blender 3.3.2
    • No changes to DNA - just a version bump for us.
  • [1.3.10][08/10/2022]: Blender 3.3.1 and Blender 2.93.11
    • Both patches without structural changes to DNA.
  • [1.3.10][11/09/2022]: Blender 3.3 (LTS) file version 3.3.6
    • Some breaking changes to DNA (mainly Curves).
    • Removed short term support versions 3.1 and 3.2 in favour of 3.3
    • Support of Blender 2.83 dropped after two years
  • [1.3.10][06/08/2022]: Blender 3.02.2 and 2.93.10
    • Just version updates -- no changes in DNA.
  • [1.3.10][10/06/2022]: Blender 3.02.1
    • Just a minor DNA update. Note that Blender file version is unchanged for some reason.
  • [1.3.10][10/06/2022]: Blender 3.02.0
    • Improved import of documentation.
    • Fixed issues with javadoc documentation.
    • Added identity hashCode method to CFacade.
    • Added equals method to CPointer.
  • [1.3.9][26/04/2022]:
    • Dropped support for non-LTS releases prior to last LTS release.
    • Dropped support LTS releases, which are no longer supported by Blender.
    • Fixed bug with source code doc extraction.
    • Now generating property file with version info to support automation.
    • Maintenance releases for Blender 2.93 and 2.83.
  • [1.3.8][24/04/2022]: Blender 3.01 (Blender file version: 3.01.02)
    • Blender 3.01 - minor changes here.
    • Started to move build and automation scripts into separate project org.cakelab.blender.io.tooling.
  • [1.3.7][04/12/2021]: Blender 3.00 (Blender file version: 3.00.42)
    • Various to DNA (see doc/CHANGES_DNA.txt).
    • Introduced name mangling for parameters to prevent conflicts with Java keywords.
    • Added mapping from int8_t to byte.
    • Standardised version number for folder names in documentation system.
  • [1.3.6][03/12/2021]: Blender 2.93.6 (Blender file version: 2.93.21)
    • Blender DNA (very) minor update.
    • Changes to DNA only affect padding of ModifierData (see doc/CHANGES_DNA.txt).
    • No changes to I/O sub-system (org.cakelab.blender.io).
  • [1.3.6][06/06/2021]: Blender 2.93.0 (Blender file version: 2.93.20)
    • Added support for new scalar type int8_t.
    • Adopted to new version of org.cakelab.json (I know .. it should be independent).
    • Blender version update (release notes)
    • Changes to DNA mostly for Nodes and introduction of Spreadsheet (see doc/CHANGES_DNA.txt).
  • [1.3.5][01/03/2021]: Blender 2.92.0 (Blender file version: 2.92.15)
    • Blender version update
    • Minor changes to DNA (see doc/CHANGES_DNA.txt).
    • Version bump of SDK due to patch release of jdoxml (I know .. it should be independent).
  • [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)

Licensing

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!

Holger Machens, 20-Jan-2023