mluTCAddTC(3dm)                                                mluTCAddTC(3dm)


NAME
     mluTCAddTC, mluTCAddFrames - digital media timecode mathematics

SYNOPSIS
     #include <dmedia/mlutimecode.h>

     MLstatus mluTCAddTC
         ( MLUtimecode * result,
           const MLUtimecode *s1,
           const MLUtimecode *s2,
            int *overflowunderflow )

     MLstatus mluTCAddFrames
         ( MLUtimecode * result,
           const MLUtimecode *s1,
           int frames,
            int *overflowunderflow )


TYPES
     MLUtimecode     A structure containing a representation of SMPTE time
                     code on which certain mathematical and utility functions
                     can be performed.  Can be used with:  mluTCAddTC(3dm),
                     mluTCAddFrames(3dm), mluTCToString(3dm),
                     mluTCFromSeconds(3dm), mluTCToSeconds(3dm),
                     mluTCFromString(3dm), mluTCFramesPerDay(3dm) , and
                     mluTCFramesBetween(3dm). See also MLUtimecode(3dm).


ARGUMENTS
     result          The result of the addition operation.  Note that this
                     must be a valid pointer, and should not point to the same
                     MLUtimecode 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).


Copyright SGI 2000    CONFIDENTIAL DRAFT                                Page 1


DESCRIPTION
     mluTCAddTC 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.  mluTCAddTC will return ML_STATUS_INVALID_ARGUMENT
     if the addition failed.  See RETURN VALUE.

     mluTCAddFrames 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 mluTCAddFrames should be checked to verify that there was no
     underflow condition.


RETURN VALUE
     If a MLUtimecode operand (s1 or s2) contains an illegal timecode value
     (e.g., a negative entry, invalid frame number, these functions will
     return MLU_STATUS_INVALID_ARGUMENT, 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 MLU_STATUS_NO_ERROR, 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.

     mluTCAddTC and mluTCAddFrames return MLU_STATUS_NO_ERROR upon successful
     completion of the addition operation.


NOTES
     In order for MLUtimecode's of differing tc_type (e.g., MLU_TC_30_ND and
     MLU_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 MLUtimecode's with
     different tc_type's, different results may be obtained by adding them as
     seconds or as frames--which is why mluTCAddTC does not allow two
     MLUtimecode's of different tc_type's to be added.


SEE ALSO
     mluTCFramesBetween(3dm), mluTCFramesPerDay(3dm), mluTCFromSeconds(3dm),
     mluTCFromString(3dm), mluTCFromString(3dm), mluTCToSeconds(3dm).


     Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.


Copyright SGI 2000    CONFIDENTIAL DRAFT                                Page 2