[Bf-blender-cvs] [64cdcf7973f] blenloader-decentralization: improve documentation
Jacques Lucke
noreply at git.blender.org
Sun May 3 16:04:07 CEST 2020
Commit: 64cdcf7973f34698e7376ac17df94f9672c26faa
Author: Jacques Lucke
Date: Sun May 3 15:38:51 2020 +0200
Branches: blenloader-decentralization
https://developer.blender.org/rB64cdcf7973f34698e7376ac17df94f9672c26faa
improve documentation
===================================================================
M source/blender/blenloader/BLO_read_write.h
M source/blender/blenloader/intern/writefile.c
===================================================================
diff --git a/source/blender/blenloader/BLO_read_write.h b/source/blender/blenloader/BLO_read_write.h
index 064d7b3cd78..e15ec830178 100644
--- a/source/blender/blenloader/BLO_read_write.h
+++ b/source/blender/blenloader/BLO_read_write.h
@@ -14,6 +14,29 @@
* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
+/** \file
+ * \ingroup blenloader
+ *
+ * API that allows different parts of Blender to define what data is stored in .blend files.
+ *
+ * Four callbacks have to be provided to fully implement .blend I/O for a piece of data. One of
+ * those is related to file writing and three for file reading. Reading requires multiple
+ * callbacks, due to the way linking between files works.
+ *
+ * Quick description of the individual callbacks:
+ * - Blend Write: Define which structs and memory buffers are saved.
+ * - Blend Read Data: Loads structs and memory buffers from file and updates pointers them.
+ * - Blend Read Lib: Updates pointers to ID data blocks.
+ * - Blend Expand: Defines which other data blocks should be loaded (possibly from other files).
+ *
+ * Each of these callbacks uses a different API functions.
+ *
+ * Some parts of Blender, e.g. modifiers, don't require you to implement all four callbacks.
+ * Instead only the first two are necessary. The other two are handled by general ID management. In
+ * the future, we might want to get rid of those two callbacks entirely, but for now they are
+ * necessary.
+ */
+
#ifndef __BLO_READ_WRITE_H__
#define __BLO_READ_WRITE_H__
@@ -28,70 +51,90 @@ typedef struct BlendDataReader BlendDataReader;
typedef struct BlendLibReader BlendLibReader;
typedef struct BlendExpander BlendExpander;
+/* ************************************************ */
/* API for file writing.
- **********************************************/
-
-/**
- * When NULL is passed as data_ptr, nothing is done.
+ *
+ * Most functions fall into one of two categories. Either they write a DNA struct or a raw memory
+ * buffer to the .blend file.
+ *
+ * It is safe to pass NULL as data_ptr. In this case nothing will be stored.
+ *
+ * DNA Struct Writing
+ * ------------------
+ *
+ * Functions dealing with DNA structs begin with BLO_write_struct_*.
+ *
+ * DNA struct types can be identified in different ways:
+ * - Run-time Name: The name is provided as const char *.
+ * - Compile-time Name: The name is provided at compile time. This can be more efficient. Note
+ * that this optimization is not implemented currently.
+ * - Struct ID: Every DNA struct type has an integer ID that can be queried with
+ * BLO_get_struct_id_by_name. Providing this ID can be a useful optimization when many structs
+ * of the same type are stored AND if those structs are not in a continuous array.
+ *
+ * Often only a single instance of a struct is written at once. However, sometimes it is necessary
+ * to write arrays or linked lists. Separate functions for that are provided as well.
+ *
+ * There is a special macro for writing id structs: BLO_write_id_struct. Those are handled
+ * differently from other structs.
+ *
+ * Raw Data Writing
+ * ----------------
+ *
+ * At the core there is BLO_write_raw, which can write arbitrary memory buffers to the file. The
+ * code that reads this data might have to correct its byte-order. For the common cases there are
+ * convenience functions that write and read arrays of simple types such as int32. Those will
+ * correct endianness automatically.
*/
-/**
- * Write a single DNA struct to the file.
- */
+/* Mapping between names and ids. */
+int BLO_get_struct_id_by_name(BlendWriter *writer, const char *struct_name);
+#define BLO_get_struct_id(writer, struct_name) BLO_get_struct_id_by_name(writer, #struct_name)
+
+/* Write single struct. */
void BLO_write_struct_by_name(BlendWriter *writer, const char *struct_name, const void *data_ptr);
+void BLO_write_struct_by_id(BlendWriter *writer, int struct_id, const void *data_ptr);
+#define BLO_write_struct(writer, struct_name, data_ptr) \
+ BLO_write_struct_by_id(writer, BLO_get_struct_id(writer, struct_name), data_ptr)
+
+/* Write struct array. */
void BLO_write_struct_array_by_name(BlendWriter *writer,
const char *struct_name,
int array_size,
const void *data_ptr);
-void BLO_write_struct_by_id_at_address(BlendWriter *writer,
- int struct_data,
- const void *data_ptr,
- const void *address);
-
-void BLO_write_struct_by_id(BlendWriter *writer, int struct_id, const void *data_ptr);
void BLO_write_struct_array_by_id(BlendWriter *writer,
int struct_id,
int array_size,
const void *data_ptr);
+#define BLO_write_struct_array(writer, struct_name, array_size, data_ptr) \
+ BLO_write_struct_array_by_id( \
+ writer, BLO_get_struct_id(writer, struct_name), array_size, data_ptr)
+
+/* Write struct list. */
+void BLO_write_struct_list_by_name(BlendWriter *writer,
+ const char *struct_name,
+ struct ListBase *list);
void BLO_write_struct_list_by_id(BlendWriter *writer, int struct_id, struct ListBase *list);
+#define BLO_write_struct_list(writer, struct_name, list_ptr) \
+ BLO_write_struct_list_by_id(writer, BLO_get_struct_id(writer, struct_name), list_ptr)
+/* Write id struct. */
void blo_write_id_struct(BlendWriter *writer,
int struct_id,
const void *id_address,
const struct ID *id);
-
-int BLO_get_struct_id_by_name(BlendWriter *writer, const char *struct_name);
-#define BLO_get_struct_id(writer, struct_name) BLO_get_struct_id_by_name(writer, #struct_name)
-
-#define BLO_write_struct(writer, struct_name, data_ptr) \
- BLO_write_struct_by_id(writer, BLO_get_struct_id(writer, struct_name), data_ptr)
-#define BLO_write_struct_array(writer, struct_name, array_size, data_ptr) \
- BLO_write_struct_array_by_id( \
- writer, BLO_get_struct_id(writer, struct_name), array_size, data_ptr)
-#define BLO_write_struct_list(writer, struct_name, list_ptr) \
- BLO_write_struct_list_by_id(writer, BLO_get_struct_id(writer, struct_name), list_ptr)
#define BLO_write_id_struct(writer, struct_name, id_address, id) \
blo_write_id_struct(writer, BLO_get_struct_id(writer, struct_name), id_address, id)
-/**
- * Write the data in the given memory buffer to the file. The pointer is used to identify the
- * buffer when the file is loaded.
- */
+/* Write raw data. */
void BLO_write_raw(BlendWriter *writer, int size_in_bytes, const void *data_ptr);
-
-/**
- * Wrappers around BLO_write_raw that are more convenient in many cases.
- */
void BLO_write_int32_array(BlendWriter *writer, int size, const int32_t *data_ptr);
void BLO_write_uint32_array(BlendWriter *writer, int size, const uint32_t *data_ptr);
void BLO_write_float_array(BlendWriter *writer, int size, const float *data_ptr);
void BLO_write_float3_array(BlendWriter *writer, int size, const float *data_ptr);
-void BLO_write_string(BlendWriter *writer, const char *str);
+void BLO_write_string(BlendWriter *writer, const char *data_ptr);
-/**
- * Sometimes different data is written depending on whether the file is saved to disk or used for
- * undo. This function returns true when the current file-writing is done for undo.
- */
+/* Misc. */
bool BLO_write_is_undo(BlendWriter *writer);
/* API for data pointer reading.
diff --git a/source/blender/blenloader/intern/writefile.c b/source/blender/blenloader/intern/writefile.c
index c064087fbaf..5fb15d663dc 100644
--- a/source/blender/blenloader/intern/writefile.c
+++ b/source/blender/blenloader/intern/writefile.c
@@ -4109,6 +4109,11 @@ void BLO_write_struct_list_by_id(BlendWriter *writer, int struct_id, ListBase *l
writelist_nr(writer->wd, DATA, struct_id, list);
}
+void BLO_write_struct_list_by_name(BlendWriter *writer, const char *struct_name, ListBase *list)
+{
+ BLO_write_struct_list_by_id(writer, BLO_get_struct_id_by_name(writer, struct_name), list);
+}
+
void blo_write_id_struct(BlendWriter *writer, int struct_id, const void *id_address, const ID *id)
{
writestruct_at_address_nr(writer->wd, GS(id->name), struct_id, 1, id_address, id);
@@ -4141,6 +4146,9 @@ void BLO_write_float3_array(BlendWriter *writer, int size, const float *data_ptr
BLO_write_raw(writer, sizeof(float) * 3 * size, data_ptr);
}
+/**
+ * Write a null terminated string.
+ */
void BLO_write_string(BlendWriter *writer, const char *str)
{
if (str != NULL) {
@@ -4148,6 +4156,10 @@ void BLO_write_string(BlendWriter *writer, const char *str)
}
}
+/**
+ * Sometimes different data is written depending on whether the file is saved to disk or used for
+ * undo. This function returns true when the current file-writing is done for undo.
+ */
bool BLO_write_is_undo(BlendWriter *writer)
{
return writer->wd->use_memfile;
More information about the Bf-blender-cvs
mailing list