69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
Blender Cloud addon
|
|
===================
|
|
|
|
Installation requires the [Pillar SDK](https://github.com/armadillica/pillar-python-sdk)
|
|
to be installed. It can either be installed regularly somewhere on
|
|
the Python PATH, or be stored as a [wheel file](http://pythonwheels.com/)
|
|
at `blender_cloud/wheels/pillar_sdk-*.whl`.
|
|
|
|
|
|
Communication & File Structure
|
|
------------------------------
|
|
|
|
### Assumptions
|
|
|
|
* Cache is user-global, stored in an OS-specific location, and can be removed/recreated. This
|
|
document refers to that location as `$CACHE`, and is typically a directory like
|
|
`$HOME/.cache/blender/blender_cloud`. Also see
|
|
[T47684](https://developer.blender.org/T47684). This directory should not be tied to the
|
|
version of Blender -- malformed/invalid caches should just be ignored or removed.
|
|
* At the moment, versioning of files is limited to re-syncing to get the latest versions. More
|
|
extensive versioning falls under the umbrella of "asset management" and is out of scope of
|
|
this addon.
|
|
* Users can download texture nodes. Such a download may result in multiple files on the local
|
|
filesystem (think of one texture node containing diffuse, bump and specular maps).
|
|
|
|
### Caching
|
|
|
|
Caching is performed at different levels:
|
|
|
|
* Caching of HTTP GET requests is performed by [CacheControl](https://cachecontrol.readthedocs.org/).
|
|
|
|
* Cache is stored in `$CACHE/{username}/blender_cloud_http/`; by using the file
|
|
backend, we ensure cache persistence across Blender runs. This
|
|
does require the `lockfile` package to be installed or bundled.
|
|
* The code is cache-aware and uses the CacheControl-managed session object.
|
|
This allows for more granular control over where in the code cache is (not) used.
|
|
* Uncached HTTP requests user another session object to allow
|
|
connection pooling.
|
|
|
|
* Downloaded thumbnails are cached (by us) in `$CACHE/thumbnails/{node_uuid}/{filename}`.
|
|
|
|
* Use a non-cached HTTP GET to download these.
|
|
* A subset of HTTP headers are stored as JSON key/value pairs in `$CACHE/thumbnails/{node_uuid}/{filename}.headers`.
|
|
* Use the ETag and If-Modified-Since headers to prevent unnecessary re-downloading.
|
|
* Check Content-Length header against actual file size to detect partially-downloaded files that need re-downloading.
|
|
* A file download is only attempted once per Blender session.
|
|
|
|
* Downloaded files (such as textures) are handled in the same way as thumbnails (described above),
|
|
but have their metadata stored somewhere else (described below).
|
|
|
|
### Filesystem Layout
|
|
|
|
* Top-level texture directory, referred to as `$TEXTURES` in this document, can be configured per
|
|
Blender scene. It defaults to a global addon preference, which in turns defaults to `//textures`.
|
|
* Texture files are stored in `$TEXTURES/{project_name}/{node_name}/{node_name}/.../{file_variant}-{file_name}`.
|
|
`{file_variant}` is "col" for colour/diffuse textures, "nor" for normal/bump textures, etc.
|
|
* Metadata is stored in `$TEXTURES/.blender_cloud`, with the following subdirectories:
|
|
|
|
* `files/{file_uuid}.json` containing the file document from Pillar
|
|
* `files/{file_uuid}.headers` containing a subset of the HTTP headers received while downloading the file
|
|
|
|
In the future we might add:
|
|
|
|
* `projects/{project_uuid}.json` containing the project document from Pillar
|
|
* `nodes/{node_uuid}.json` containing the node document from Pillar
|
|
* `index.sqlite` containing a mapping from `{project_name}/{node_name}/{node_name}/...`
|
|
to the UUID of the last-named path component (project, node, or file). This allows us
|
|
to map the path of a filesystem path to its Pillar document.
|