IMB_metadata improvements

- Metadata handling is now separate from `ImBuf *`, allowing it to be
  used with a generic `IDProperty *`.
- Merged `IMB_metadata_add_field()` and `IMB_metadata_change_field()`
  into a more robust `IMB_metadata_set_field()`. This new function
  doesn't return any status (it now always succeeds, and the previously
  existing return value was never checked anyway).
- Removed `IMB_metadata_del_field()` as it was never actually used
  anywhere.
- Use `IMB_metadata_ensure()` instead of having
  `IMB_metadata_set_field()` create the containing `IDProperty` for
  you.
- Deduplicated function declarations, moved `intern/IMB_metadata.h` out
  of `intern/`. Note that this does mean that we have some extra
  `#include "IMB_metadata.h"` lines now, as the metadata functions are
  no longer declared in `IMB_imbuf.h`.
- Deduplicated function declarations, all metadata-related declarations
  are now in imbuf/IMB_metadata.h.

Part of: https://developer.blender.org/D2273

Reviewed by: @campbellbarton

1 files changed, 77 insertions, 0 deletions

diff --git a/source/blender/imbuf/IMB_metadata.h b/source/blender/imbuf/IMB_metadata.h
new file mode 100644
index 00000000000..258d6bb1c5a
--- /dev/null
+++ b/source/blender/imbuf/IMB_metadata.h
@@ -0,0 +1,77 @@
+/*
+ * ***** BEGIN GPL LICENSE BLOCK *****
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * The Original Code is Copyright (C) 2005 Blender Foundation
+ * All rights reserved.
+ *
+ * The Original Code is: all of this file.
+ *
+ * Contributor(s): Austin Benesh. Ton Roosendaal.
+ *
+ * ***** END GPL LICENSE BLOCK *****
+ */
+
+/** \file blender/imbuf/intern/IMB_metadata.h
+ *  \ingroup imbuf
+ */
+
+
+#ifndef __IMB_METADATA_H__
+#define __IMB_METADATA_H__
+
+struct anim;
+struct ImBuf;
+struct IDProperty;
+
+/** The metadata is a list of key/value pairs (both char *) that can me
+ * saved in the header of several image formats.
+ * Apart from some common keys like
+ * 'Software' and 'Description' (png standard) we'll use keys within the
+ * Blender namespace, so should be called 'Blender::StampInfo' or 'Blender::FrameNum'
+ * etc...
+ *
+ * The keys & values are stored in ID properties, in the group "metadata".
+ */
+
+/** Ensure that the metadata property is a valid IDProperty object.
+ * This is a no-op when *metadata != NULL.
+ */
+void IMB_metadata_ensure(struct IDProperty **metadata);
+void IMB_metadata_free(struct IDProperty *metadata);
+
+/** Read the field from the image info into the field.
+ *  \param metadata - the IDProperty that contains the metadata
+ *  \param key - the key of the field
+ *  \param value - the data in the field, first one found with key is returned,
+ *                 memory has to be allocated by user.
+ *  \param len - length of value buffer allocated by user.
+ *  \return    - 1 (true) if metadata is present and value for the key found, 0 (false) otherwise
+ */
+bool IMB_metadata_get_field(struct IDProperty *metadata, const char *key, char *value, const size_t len);
+
+/** Set user data in the metadata.
+ * If the field already exists its value is overwritten, otherwise the field
+ * will be added with the given value.
+ *  \param metadata - the IDProperty that contains the metadata
+ *  \param key - the key of the field
+ *  \param value - the data to be written to the field. zero terminated string
+ */
+void IMB_metadata_set_field(struct IDProperty *metadata, const char *key, const char *value);
+
+void IMB_metadata_copy(struct ImBuf *dimb, struct ImBuf *simb);
+
+#endif /* __IMB_METADATA_H__ */