dmTCAddTC(3dm)                                                  dmTCAddTC(3dm)


NAME
     dmTCAddTC, dmTCAddFrames - digital media timecode mathematics

SYNOPSIS
     #include <dmedia/dm_timecode.h>

     DMstatus dmTCAddTC
         ( DMtimecode * result,
           const DMtimecode *s1,
           const DMtimecode *s2,
            int *overflowunderflow )

     DMstatus dmTCAddFrames
         ( DMtimecode * result,
           const DMtimecode *s1,
           int frames,
            int *overflowunderflow )


TYPES
     DMtimecode   A structure containing a representation of SMPTE time code
                  on which certain mathematical and utility functions can be
                  performed.  Can be used with:  dmTCAddTC(3dm),
                  dmTCAddFrames(3dm), dmTCToString(3dm), dmTCFromSeconds(3dm),
                  dmTCToSeconds(3dm), dmTCFromString(3dm),
                  dmTCFramesPerDay(3dm), and dmTCFramesBetween(3dm).  Can also
                  be used with the dmLTC(3dm) and dmVITC(3dm) routines.  See
                  also DMtimecode(3dm).


ARGUMENTS
     result   The result of the addition operation. Note that this must be a
              valid pointer, and should not point to the same DMtimecode as s1
              or s2.


     s1, s2   The timecode operand(s) to be used in the addition.


     frames   The number of frames to add to the operand s1.


     underflowoverflow
              An optional argument so that the user of the library can tell if
              an underflow or overflow condition occurred. If the app doesn't
              care about overflow/underflow, it should pass in NULL.
              Otherwise, underflowoverflow will be set to 0 (normal), a
              positive number (overflow), or a negative number (underflow).


DESCRIPTION
     dmTCAddTC adds operand s1 to operand s2. It returns the result of the
     addition in result. The tc_type of result will be the same as the tc_type
     of the operands. It is required that the tc_type of s1 be the same as the
     tc_type of s2. See NOTES for information on adding timecodes of differing
     tc_type. dmTCAddTC will return DM_FAILURE if the addition failed. See
     RETURN VALUE.

     dmTCAddFrames adds frames video frames to operand s1 and returns the
     result in result. The tc_type of result will be the same tc_type as s1.
     It is acceptable for frames to be a negative value, but overflowunderflow
     from dmTCAddFrames should be checked to verify that there was no
     underflow condition.


RETURN VALUE
     If a DMtimecode operand (s1 or s2) contains an illegal timecode value
     (e.g., a negative entry, invalid frame number, etc.), these functions
     will return DM_FAILURE, and the contents of result will be undefined.

     If the result of the addition overflows or underflows the 24 hour period,
     these functions will return DM_SUCCESS, and the contents of result will
     have wrapped to a 24 hour clock. The overflowunderflow parameter will
     have been set, however, on an underflow or overflow condition.

     dmTCAddTC and dmTCAddFrames return DM_SUCCESS upon successful completion
     of the addition operation.


NOTES
     In order for DMtimecode's of differing tc_type (e.g., DM_TC_30_ND and
     DM_TC_2997_4FIELD_DROP) to be added, they must first be converted to
     either frames or seconds, and added as either frames or seconds, as
     appropriate for the situation.  Note that when adding DMtimecode's with
     different tc_type's, different results may be obtained by adding them as
     seconds or as frames--which is why dmTCAddTC does not allow two
     DMtimecode's of different tc_type's to be added.


SEE ALSO
     dmTCFromSeconds(3dm), dmTCToSeconds(3dm), dmTCFromString(3dm),
     dmTCFromString(3dm), dmTCFramesPerDay(3dm), dmTCFramesBetween(3dm),
     dmLTC(3dm), dmVITC(3dm)


                                                                        Page 2