cakelab
Home Projects Research Misc. Contact

Java .Blend


Providing Type-Safe Read/Write File Access to

the Full Blender DNA in Java


Version 1.1.0


(open source and free)

02-May-2017

Holger Machens

Shortcuts
About
Documentation
Examples
Download
Change Log
Licensing

About

Blender's core is written in C and Blender files are basically dumps of native memory content (C structs and scalar types) from heap to a file on disk. A .blend file is organised in blocks of arbitrary length, and the type of data is described in a special block, which contains type information (meta data) for all C native and structured types which can exist in a .blend file.

Based on the meta data of any Blender file, it is theoretically possible to generate code, which is capable to read/write data in Blender files of the same version in any programming language. Java .Blend is a combination of a code generator and a runtime data I/O module. Together, they provide a generic (any-version) solution for Blender file import/export in Java which features all aspects of the Blender DNA data model: The code generator is used at development time to generate Java facade classes which provide a type-safe API to Blender data and the I/O module transparently supports in data access at runtime.

This toolkit was designed to serve for any kind of data exchange with Blender. Whether just importing data into another graphics engine, conversion to a different data format or external processing of data to add features to Blender. The generic mapping of the entire Blender DNA core data model combined with import and export capabilities, supports all of it.

Please note that Java .Blend does not include code for semantic conversion of data between different Blender DNA versions. Thus, a given data model generated by Java .Blend for a specific Blender version is not implicitly compatible with another version. Read more on this topic in the documentation.

Working with Blender files requires in-depth knowledge about its data model. Java .Blend's documentation provides just a high level overview of the data model and the Javadoc documentation incorporated in generated facade classes is still incomplete. Everybody is encouraged to contribute to the Javadoc source code documentation on generated classes, which is kept in a separate repository on github.

As a side effect of the generic approach, Java .Blend has low maintenance effort on maintainers side. New details in Blender's DNA will be instantly reflected in the generated data model and implicitly supported during import and export. Thus, users don't have to worry about how long they can rely on this library, they can just generate new models by themselves without touching the sources.

Download

Pregenerated Data Model Packages

These packages contain pregenerated data models including the utilities package and the data I/O submodule. The version numbers provided in the table below are Blender's version and minimum version the library is compatible with. Please note, that Java .Blend does no conversion between versions. Refer to Section "Blender Versioning and File Version" in the documentation to read more about this topic.

Note: Binaries here are under Apache License v2.0, but source code packages contain source code documentation of Java .Blend's externally maintained documentation. Thus, the source code packages are under GPLv3 (see Licensing).

If you need support for a different Blender version or do not want the dependency on GPL then refer to Section Generating Data Model and Utilities in the documentation.

version minversion
2.78-0 2.70-6 binary src javadoc
2.76-0 2.70-5 binary src javadoc
2.72-2 2.70-5 binary src javadoc
2.69-0 2.62-0 binary src javadoc

Examples

This package contains various examples for use cases of Java .Blend. Part of this package is a pregenerated Java .Blend data model for Blender v2.78. It uses LWJGL and requires a graphics card which supports OpenGL 4.3 (for no particular reason, but you should look at the source code anyway!).

An overview of the contents of the examples package is given here.

version
1.1.0 binary src
1.0.4 binary src

Java .Blend SDK

This package contains the code generator and the data I/O submodule. You will need this package if you want to generate your own data model, improve the documentation or modify Java .Blend. You should also consider downloading the documentation files below, if you want source code documentation in generated facade classes.

version
1.1.0 binary src
1.0.4 binary src

Java .Blend's Externally Maintained Documentation

Source code documentation for generated facade classes is maintained in a separate repository on github.

Link: https://github.com/homacs/JavaBlendDocs

Change Log

  • [1.1.0-r1117][18/01/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 Externally Maintained Documentation

Java .Blend's Externally Maintained 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 externally maintained 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, 02-May-2017