gd_entry - Man Page

A gd_entry_t describing any field type which permits non-literal scalar field parameters (BIT, LINCOM, MPLEX, PHASE, POLYNOM, RAW, RECIP, SBIT, or WINDOW) will also provide:

typedef struct {
  ...

  const char *scalar[GD_MAX_POLY_ORD + 1];   /* param. fields */
  int         scalar_ind[GD_MAX_POLY_ORD + 1];
                                            /* CARRAY indices */

  ...
} gd_entry_t;

Only certain elements of these arrays will be initialised:

• For BIT and SBIT fields, the first element corresponds to bitnum and the second to numbits. The remainder are uninitialised.
• For LINCOM fields, the first GD_MAX_LINCOM elements correspond to the slopes (cm) and the next GD_MAX_LINCOM elements correspond to the offsets (cb). Only the first n_fields elements of these two sets are initialised.  Notably, this means for n_fields < GD_MAX_LINCOM, there will be uninitialised elements in the middle of these arrays between the element corresponding to cm[n_fields - 1] and the element corresponding to cb[0].
• For MPLEX fields, the first element corresponds to count_val and the second to period. The remainder are uninitialised.
• For PHASE fields, the first element corresponds to shift. The remainder are uninitialised.
• For POLYNOM fields, these arrays correspond with the co-efficients ca. Only the first poly_ord + 1 elements are initialised.
• For RAW fields, the first element corresponds to spf. The remainder are uninitialised.
• For RECIP fields, the first element corresponds to cdividend. The remainder are uninitialised.
• For WINDOW fields, the first element corresponds to threshold. The remainder are uninitialised.

The scalar parameters are NULL if a literal parameter was used, or else a field code specifying the scalar parameters.

If an element of scalar specifies a CARRAY field, the corresponding scalar_ind will indicate the element of the CARRAY used.  For CONST fields, scalar_ind will be -1.

A gd_entry_t describing a BIT or SBIT entry, will also provide:

typedef struct {
  ...

  const char *in_fields[1];     /* input field code */
  int         bitnum;           /* first bit */
  int         numbits;          /* bit length */

  ...
} gd_entry_t;

The in_fields member is an array of length one containing the input field code.

The bitnum member indicates the number of the first bit (counted from zero) extracted from the input.  If this value was specified as a scalar field code, this will be the numerical value of that field, and scalar[0] will contain the field code itself, otherwise scalar[0] will be NULL.

The numbits member indicates the number of bits which are extracted from the input. If this value was specified as a scalar field code, this will be the numerical value of that field, and scalar[1] will contain the field code itself, otherwise scalar[1] will be NULL.

A gd_entry_t describing a CARRAY entry, will also provide:

typedef struct {
  ...

  gd_type_t  const_type; /* data type in format specification */
  size_t     array_len;  /* length of array data */

  ...
} gd_entry_t;

The const_type member indicates the data type of the constant value stored in the format file metadata.  See gd_getdata(3) for a list of valid values that a variable of type gd_type_t may take.

The array_len member gives the number of elements in the array.

A gd_entry_t describing a CONST entry, will also provide:

typedef struct {
  ...

  gd_type_t  const_type; /* data type in format specification */

  ...
} gd_entry_t;

The const_type member indicates the data type of the constant value stored in the format file metadata.  See gd_getdata(3) for a list of valid values that a variable of type gd_type_t may take.

A gd_entry_t describing a DIVIDE, INDIR, MULTIPLY, or SINDIR entry, will also provide:

typedef struct {
  ...

  const char *in_fields[2];     /* input field codes */

  ...
} gd_entry_t;

The in_fields member is an array of length two containing the input field codes.

A gd_entry_t describing an INDEX entry, which is used only for the implicit INDEX field, provides no additional data.

A gd_entry_t describing a LINCOM entry, will also provide:

typedef struct {
  ...

  int            n_fields;                 /* # of inputs */
  const char    *in_fields[GD_MAX_LINCOM]; /* input fields(s) */
  double complex cm[GD_MAX_LINCOM];        /* scale factor(s) */
  double         m[GD_MAX_LINCOM];         /* scale factor(s) */
  double complex cb[GD_MAX_LINCOM];        /* offset terms(s) */
  double         b[GD_MAX_LINCOM];         /* offset terms(s) */

  ...
} gd_entry_t;

The n_fields member indicates the number of input fields.  It will be between one and GD_MAX_LINCOM inclusive. GD_MAX_LINCOM is defined in getdata.h as the maximum number of input fields permitted by a LINCOM.

The in_fields member is an array of length GD_MAX_LINCOM containing the input field code(s).  Only the first n_fields elements of this array are initialised.  The remaining elements contain uninitialised data.

The cm and cb members are arrays of the scale factor(s) and offset term(s) for the LINCOM. Only the first n_fields elements of these array contain meaningful data. If any of these values were specified as a scalar field code, this will be the numerical value of that field.  The field code corresponding to cm[i] will be stored in scalar[i] and the field code associated with cb[i] will be stored in scalar[i + GD_MAX_LINCOM]. Otherwise the corresponding scalar member will be NULL. See Notes below on changes to the declaration of cm and cb when using the C89 GetData API.

The elements of m and b are the real parts of the corresponding elements of cm and cb.

A gd_entry_t describing a LINTERP entry, will also provide:

typedef struct {
  ...

  const char *table             /* linterp table filename */
  const char *in_fields[1];     /* input field code */

  ...
} gd_entry_t;

The table member is the pathname to the look up table on disk.  This the path as it appars in the format specification.  It may be a path relative to the fragment directory.  For an canonicalised, absolute version of this path, see gd_linterp_tablename(3).

The in_fields member is an array of length one containing the input field code.

A gd_entry_t describing a MPLEX entry, will also provide:

typedef struct {
  ...

  const char *in_fields[2];   /* input field codes */
  int         count_val;      /* value of the multiplex index */
  int         period;         /* samples between successive
                                                      indices */

  ...
} gd_entry_t;

The in_fields member contains the field codes of the input field (element 0) and the multiplex index field (element 1).

The count_val member is the value of the multiplex index field when the output field is stored in the input field.

The period member is the number of samples between successive occurrances of count_val in the index vector, or zero, if this is not known or constant.  This is only used to determine how far to look back for a starting value for the output field; see gd_mplex_lookback(3).

A gd_entry_t describing a PHASE entry, will also provide:

typedef struct {
  ...

  const char *in_fields[1];     /* input field code */
  gd_int64_t  shift;            /* phase shift */

  ...
} gd_entry_t;

The in_fields member is an array of length one containing the input field code.

The shift member indicates the shift in samples.  The gd_int64_t type is a 64-bit signed integer type.  A positive value indicates a shift forward in time (towards larger frame numbers).  If this value was specified as a scalar field code, this will be the numerical value of that field, and scalar[0] will contain the field code itself, otherwise scalar[0] will be NULL.

A gd_entry_t describing a POLYNOM entry, will also provide:

typedef struct {
  ...

  int            poly_ord;                /* polynomial order */
  const char    *in_fields[1];            /* input field(s) */
  double complex ca[GD_MAX_POLY_ORD + 1]; /* co-efficients(s) */
  double         a[GD_MAX_POLY_ORD + 1];  /* co-efficients(s) */

  ...
} gd_entry_t;

The poly_ord member indicates the order of the polynomial.  It will be between one and GD_MAX_POLY_ORD inclusive. GD_MAX_POLY_ORD is defined in getdata.h as the maximum order of polynomial permitted by a POLYNOM.

The in_fields member is an array of length one containing the input field code.

The ca members are arrays of the co-efficient(s) for the POLYNOM. Only the first poly_ord + 1 elements of this array contains meaningful data.  If any of these values were specified as a scalar field code, this will be the numerical value of that field.  The field code corresponding to ca[i] will be stored in scalar[i]. Otherwise the corresponding scalar member will be NULL.  See Notes below on changes to the declaration of ca when using the C89 GetData API.

The elements of a are the real parts of the corresponding elements of ca.

A gd_entry_t describing a RAW entry, will also provide:

typedef struct {
  ...

  unsigned int  spf;          /* samples per frame on disk */
  gd_type_t     data_type;    /* data type on disk */

  ...
} gd_entry_t;

The spf member contains the samples per frame of the binary data on disk.  If this value was specified as a scalar field code, this will be the numerical value of that field, and scalar[0] will contain the field code itself, otherwise scalar[0] will be NULL.

The data_type member indicates the data type of the binary data on disk.  See gd_getdata(3) for a list of valid values that a variable of type gd_type_t may take.

A gd_entry_t describing a RECIP entry, will also provide:

typedef struct {
  ...

  const char    *in_fields[1];         /* input field code */
  double complex cdividend;            /* scalar dividend */
  double         dividend;             /* scalar dividend */

  ...
} gd_entry_t;

The in_fields member is an array of length one containing the input field code.

The cdividend member provides the constant dividend of the computed division.  If this value was specified as a scalar field code, this will be the numerical value of that field, and scalar[0] will contain the field code itself, otherwise scalar[0] will be NULL.  The dividend member contains the real part of cdividend.

A gd_entry_t describing a STRING entry provides no additional data.

A gd_entry_t describing a WINDOW entry, will also provide:

typedef struct {
  ...

  const char    *in_fields[2];  /* input field codes */
  gd_windop_t   windop;         /* comparison operator */
  gd_triplet_t  threshold;      /* the value compared against */

  ...
} gd_entry_t;

The in_fields member contains the field codes of the input field (element 0) and the check field (element 1).

The windop member equals one of the following symbols, indicating the particular comparison performed on the check field:

GD_WINDOP_EQ

data are extracted when the check field equals threshold;

GD_WINDOP_GE

data are extracted when the check field is greater than or equal to threshold;

GD_WINDOP_GT

data are extracted when the check field is strictly greater than threshold;

GD_WINDOP_LE

data are extracted when the check field is less than or equal to threshold;

GD_WINDOP_LT

data are extracted when the check field is strictly less than threshold;

GD_WINDOP_NE

data are extracted when the check field is not equal to threshold;

GD_WINDOP_SET

data are extracted when at least one bit in threshold is also set in the check field;

GD_WINDOP_CLR

data are extracted when at least one bit in threshold is not set in the check field.

The threshold is the value against which the check field is compared.  The gd_triplet_t type is defined as:

typedef union {
  gd_int64_t i;
  gd_uint64_t u;
  double r;
} gd_triplet_t;

The particular element of the union to use depends on the value of windop:

• For GD_WINDOP_EQ and GD_WINDOP_NE, the signed integer element, threshold.i, is set;
• For GD_WINDOP_SET and GD_WINDOP_CLR, the unsigned integer element, threshold.u, is set;
• For all other values of windop, the floating point element, threshold.r, is set.

Field-type specific members have been added to the structure as support for those field types have been introduced to the library:

• BIT, LINCOM, LINTERP, MULTIPLY, PHASE, and RAW were supported in GetData-0.3.0 (Dirfile Standards Version 5).
• CONST and STRING entries were introduced in GetData-0.4.0 (Dirfile Standards Version 6); this is also the first version that treats INDEX as a normal field.  In earlier versions, trying to retrieve the metadata for the INDEX field would fail.
• POLYNOM and SBIT entries were introduced in GetData-0.6.0 (Dirfile Standards Version 7).
• CARRAY, DIVIDE, and RECIP entries were introduced in GetData-0.7.0 (Dirfile Standards Version 8).
• MPLEX and WINDOW entries were introduced in GetData-0.8.0 (Dirfile Standards Version 9).
• INDIR, SARRAY, and SINDIR entries were introduced in GetData-0.10.0 (Dirfile Standards Version 10).

The scalar member appeared in GetData-0.6.0.  This release also introduced the complex-valued scalar members (cm, cb, &c.)

The scalar_ind member appeared in GetData-0.7.0.  This was also the first release with a working ANSI C (C89) conforming alternate definition.

Before Getdata-0.8.4, the period member for MPLEX data was named count_max.

Before GetData-0.9.0, the flags member is missing.  In it's place was:

which was non-zero to indicate complex-valued parameters, which is now indicated by the GD_EN_COMPSCAL flag.