annotate m_struct.h @ 27518:e54c9b7eb0d8

Revert bad changes to SSA/ASS subtitle packet format The following commits are reverted partially or completely: "a valid ASS line contains 9 ',' before actual text" "demux_mkv: output correctly formated ASS packets" "libass: add a new ass_process_data() to process demuxed subtitle packets" These commits converted the internal representation of SSA/ASS subtitle packets from the format used by Matroska to a custom format where each packet has contents exactly matching one line in complete SSA script files. AFAIK no files natively use such a format for muxed subtitles. The stated reason for this change was to use a format that could in principle be muxed into a maximal number of containers. SSA subtitles do not have an implicit duration so both start time and duration or end time need to be specified explicitly; the new format moved timing information inside the codec packet data so it could be muxed without modification into containers that can represent only start time at the container level. However such a change is wrong from the viewpoint of program architecture. Timing information belongs to the demuxer level, but these commits moved not only the duration but also the authoritative value of the start time to inside the codec data. Additionally the new format lost the value of the Matroska ReadOrder field which is used by MPlayer. This commit changes the internal packet format back to that used by Matroska and makes the internal Matroska demuxer output that format again. Libavformat still outputs the "new" format; it could be converted back to the Matroska format in demux_lavf.c, but I'm not adding that code at least yet. The current lavf code has similar problems as the reverted code in MPlayer, and it also currently fails to provide any way to access the value of the ReadOrder field. I hope that the lavf side will be improved; if it isn't conversion can be added later. For now I'll make MPlayer default to the internal Matroska demuxer instead of the lavf one in a separate commit.

#ifndef MPLAYER_M_STRUCT_H
#define MPLAYER_M_STRUCT_H

/// \defgroup OptionsStruct Options struct
/// \ingroup Options
/// An API to manipulate structs using m_option.
///@{

/// \file m_struct.h

struct m_option;

/// Struct definition
typedef struct m_struct_st {
  /// For error messages and debugging
  const char* name;
  /// size of the whole struct
  unsigned int size;
  /// Pointer to a struct filled with the default settings
  const void* defaults;
  /// Field list.
  /** The p field of the \ref m_option struct must contain the offset
   *  of the member in the struct (use M_ST_OFF macro for this).
   */
  const struct m_option* fields;
} m_struct_t;


// From glib.h (modified ;-)

/// Get the offset of a struct field.
/** \param struct_type Struct type.
 *  \param member Name of the field.
 *  \return The offset of the field in bytes.
 */
#define M_ST_OFF(struct_type, member)    \
    ((void*) &((struct_type*) 0)->member)

/// Get a pointer to a struct field.
/** \param struct_p Pointer to the struct.
 *  \param struct_offset Offset of the field in the struct.
 *  \return Pointer to the struct field.
 */
#define M_ST_MB_P(struct_p, struct_offset)   \
    ((void *)((char *)(struct_p) + (unsigned long)(struct_offset)))

/// Access a struct field at a given offset.
/** \param member_type Type of the field.
 *  \param struct_p Pointer to the struct.
 *  \param struct_offset Offset of the field in the struct.
 *  \return The struct field at the given offset.
 */
#define M_ST_MB(member_type, struct_p, struct_offset)   \
    (*(member_type*) M_ST_MB_P ((struct_p), (struct_offset)))



/// Allocate the struct and set it to the defaults.
/** \param st Struct definition.
 *  \return The newly allocated object set to default.
 */
void*
m_struct_alloc(const m_struct_t* st);

/// Set a field of the struct.
/** \param st Struct definition.
 *  \param obj Pointer to the struct to set.
 *  \param field Name of the field to set.
 *  \param param New value of the field.
 *  \return 0 on error, 1 on success.
 */
int
m_struct_set(const m_struct_t* st, void* obj, char* field, char* param);

/// Reset a field (or all if field == NULL) to defaults.
/** \param st Struct definition.
 *  \param obj Pointer to the struct to set.
 *  \param field Name of the field to reset, if NULL all fields are reseted.
 */
void
m_struct_reset(const m_struct_t* st, void* obj, const char* field);

/// Create a copy of an existing struct.
/** \param st Struct definition.
 *  \param obj Pointer to the struct to copy.
 *  \return Newly allocated copy of obj.
 */
void*
m_struct_copy(const m_struct_t* st, void* obj);

/// Free an allocated struct.
/** \param st Struct definition.
 *  \param obj Pointer to the struct to copy.
 */
void
m_struct_free(const m_struct_t* st, void* obj);

/// Get a field description.
/** \param st Struct definition.
 *  \param f Name of the field.
 *  \return The \ref m_option struct describing the field or NULL if not found.
 */
const struct m_option*
m_struct_get_field(const m_struct_t* st,const char* f);

///@}

#endif /* MPLAYER_M_STRUCT_H */