|
1 | | -# rdf-public |
2 | | -Public-facing, open-source capable RDF repository. |
| 1 | +# RDF |
| 2 | + |
| 3 | +Radeon data file library. Check the [specification](docs/specification.md) for details about the file format. |
| 4 | + |
| 5 | +This repository contains the main library (`amdrdf`) as well as a few useful binaries: |
| 6 | + |
| 7 | +* `rdfm` merges two files together (assuming they contain disjoint data) |
| 8 | +* `rdfi` dumps information about a file (what chunks it contains, etc.) |
| 9 | +* `rdfg` generates a chunk file from a JSON description (useful for testing) |
| 10 | + |
| 11 | +## Overview |
| 12 | + |
| 13 | +RDF files consist of named chunks. You can think of a file as a list of chunks that you can index using a name. File formats are built on top of RDF by defining chunk names and chunk contents. If you need a new file format, all you need to agree on is a unique set of chunk names and you're good to go. Chunks can be optionally compressed and versioned, which removes the need for versioning whole files. |
| 14 | + |
| 15 | +The same chunk can appear multiple times in a file. They'll get enumerated so it's perfectly fine to have a `Mesh` chunk for each mesh and simply add as often as needed. The full chunk identifier is the chunk name and the index. Chunks are always consecutively numbered in a file. |
| 16 | + |
| 17 | +A chunk consists of a header and the data. The difference between those is that the header is always uncompressed and meant to contain only very little data (they might get all loaded in memory for instance). The data part can be optionally compressed. |
| 18 | + |
| 19 | +There is a C and a C++ API. The C API is the "low level" API that is exported from the DLL/shared object. RDF also comes with a C++ wrapper that uses the C API to simplify usage. |
| 20 | + |
| 21 | +Chunk files are assumed to be immutable, so the code is split into a `ChunkFile` class which represents the (immutable) file, and a `ChunkFileWriter` which can be used to create a new file. Additionally, RDF exposes a stream abstraction to allow reading/writing from disk, memory, or other sources. |
| 22 | + |
| 23 | +## Versioning |
| 24 | + |
| 25 | +The `amdrdf` library provides the following forwards/backwards compatibility guarantees: |
| 26 | + |
| 27 | +* For the same major version, any minor version will only *add* new entry points and enumeration values, but existing entry points will not change. Using a higher minor version is always safe. Files created by a newer library *may* not be compatible with older files if new features are used. For example, a new compression codec could be added as part of a minor API change as this is an extension only. However, as long as no new feature is used, all files produced by a newer minor version will remain compatible with older minor versions. |
| 28 | +* New major versions *may* add, remove or change entry points. Files created by a newer major version *may* not be compatible with older *major* versions. Files created by an older major version will be supported for *at least* the next higher major version. |
| 29 | +* A minor version can deprecate a function, but that function can be only removed in the next major release. |
| 30 | + |
| 31 | +Use `RDF_INTERFACE_VERSION` and `RDF_MAKE_VERSION` to check for the library version. |
0 commit comments