doc: clarify when manual struct edits are allowed

2 files changed, 59 insertions, 0 deletions

diff --git a/libass/ass.h b/libass/ass.h
index c7ff8d9..5044081 100644
--- a/libass/ass.h
+++ b/libass/ass.h
@@ -627,6 +627,7 @@ void ass_free_track(ASS_Track *track);
  * \brief Allocate new style.
  * \param track track
  * \return newly allocated style id >= 0, or a value < 0 on failure
+ * See GENERAL NOTE in ass_types.h.
  */
 int ass_alloc_style(ASS_Track *track);
 
@@ -634,6 +635,7 @@ int ass_alloc_style(ASS_Track *track);
  * \brief Allocate new event.
  * \param track track
  * \return newly allocated event id >= 0, or a value < 0 on failure
+ * See GENERAL NOTE in ass_types.h.
  */
 int ass_alloc_event(ASS_Track *track);
 
@@ -642,6 +644,12 @@ int ass_alloc_event(ASS_Track *track);
  * \param track track
  * \param sid style id
  * Deallocates style data. Does not modify track->n_styles.
+ * Freeing a style without subsequently setting track->n_styles
+ * to a value less than or equal to the freed style id before calling
+ * any other libass API function on the track is undefined behaviour.
+ * Additionally a freed style style still being referenced by an event
+ * in track->events will also result in undefined behaviour.
+ * See GENERAL NOTE in ass_types.h.
  */
 void ass_free_style(ASS_Track *track, int sid);
 
@@ -650,6 +658,10 @@ void ass_free_style(ASS_Track *track, int sid);
  * \param track track
  * \param eid event id
  * Deallocates event data. Does not modify track->n_events.
+ * Freeing an event without subsequently setting track->n_events
+ * to a value less than or equal to the freed event id before calling
+ * any other libass API function on the track is undefined behaviour.
+ * See GENERAL NOTE in ass_types.h
  */
 void ass_free_event(ASS_Track *track, int eid);
 
diff --git a/libass/ass_types.h b/libass/ass_types.h
index 6a6877e..9148e7f 100644
--- a/libass/ass_types.h
+++ b/libass/ass_types.h
@@ -22,6 +22,53 @@
 
 #include <stdint.h>
 
+/**
+ * GENERAL NOTE regarding the definitions exposed by this header
+ *
+ * The main use case for this is _reading_ the track fields, especially
+ * track->YCbCrMatrix, to correctly display the rendering results.
+ *
+ * Furthermore, the exposed definitions also open up the possibility to _modify_
+ * the exposed structs, working closer to library internals and bypassing
+ * e.g. creation of intermediate ASS-text buffers when creating dynamic events.
+ * This is an advanced use case and should only be done when well-versed in ASS
+ * and aware of the effects and legal values of _all_ fields of the structs.
+ * The burden of sanitising and correctly initialising fields is then also
+ * placed on the API user.
+ * By nature of direct struct modifications working closer to library internals,
+ * workflows that make use of this possibility are also more likely to be
+ * affected by future API breaks than those which do not.
+ *
+ * To avoid desynchronisation with internal states, there are some restrictions
+ * on when and how direct struct modification can be performed.
+ * Ignoring them may lead to undefined behaviour. See the following listing:
+ *
+ *  - Manual struct edits and track-modifying (including modification to the
+ *    event and style elements of the track) API calls cannot be freely mixed:
+ *    - Before manual changes are performed, it is allowed to call any such API,
+ *      unless the documentation of the funtion says otherwise.
+ *    - After manual changes have been performed, no track-modifying API may be
+ *      invoked, except for ass_track_set_feature and ass_flush_events.
+ *  - After the first call to ass_render_frame, existing array members
+ *    (e.g. members of events) and non-array track fields (e.g. PlayResX
+ *    or event_format) must not be modified. Adding new members to arrays
+ *    and updating the corresponding counter remains allowed.
+ *  - Adding and removing members to array fields, like events or styles,
+ *    must be done through the corresponding API function, e.g. ass_alloc_event.
+ *    See the documentation of these functions.
+ *  - The memory pointed to by string fields (char *) must be
+ *    free'able by the implementation of free used by libass.
+ *
+ * A non-exhaustive list of examples of track-modifying API functions:
+ *   ass_process_data, ass_process_codec_private,
+ *   ass_process_chunk, ass_read_styles, ...
+ *
+ * Direct struct modification can be done safely, but it is also easy to
+ * miss an initialisation or violate these restrictions, thus introducing bugs
+ * that may not manifest immediately. It should be carefully considered
+ * whether this is worthwhile for the desired use-case.
+ */
+
 #define VALIGN_SUB 0
 #define VALIGN_CENTER 8
 #define VALIGN_TOP 4