home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audio / alGetFrameTime.z / alGetFrameTime
Encoding:
Text File  |  2002-10-03  |  6.8 KB  |  133 lines
  1.  
  2.  
  3.  
  4. aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee((((3333ddddmmmm))))                                        aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alGetFrameTime - Get the time at which a sample frame came in or will go
  10.      out
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  14.  
  15.      iiiinnnntttt aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee((((ccccoooonnnnsssstttt AAAALLLLppppoooorrrrtttt ppppoooorrrrtttt,,,, ssssttttaaaammmmpppp____tttt ****ffffnnnnuuuummmm,,,, ssssttttaaaammmmpppp____tttt ****ttttiiiimmmmeeee))))
  16.  
  17. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS
  18.      _p_o_r_t expects the AAAALLLLppppoooorrrrtttt structure for the audio port for which you wish
  19.           to know the sample frame number.  This structure is the returned
  20.           value of the aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm)))) call.
  21.  
  22.      _f_n_u_m expects a pointer to an unsigned 64-bit value which is to contain
  23.           the resultant sample-frame number.
  24.  
  25.      _t_i_m_e expects a pointer to an unsigned 64-bit value which is to contain
  26.           the resultant sample-frame time, in nanoseconds.
  27.  
  28. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  29.      aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee returns an atomic pair of (fnum, time) for the device to
  30.      which _p_o_r_t is connected. For an input device, the time returned is the
  31.      time at which the returned sample frame arrived at the electrical input
  32.      on the machine. For an output device, the time returned is the time at
  33.      which the returned sample frame will arrive at the electrical output on
  34.      the machine.
  35.  
  36.      The application cannot request a specific pair of values; aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee
  37.      merely returns the most recent pair available. It is up to the
  38.      application to use this pair to calculate the time associated with a
  39.      particular sample-frame, or the sample-frame number associated with a
  40.      particular time, if desired.
  41.  
  42.      In general, the returned sample frame will not currently be in any
  43.      application's port. For example, an input sample frame as returned by
  44.      aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee may be "in the future": it has not yet arrived in any
  45.      application's port. Similarly, an output sample frame may be "in the
  46.      past": it has already gone out of some application's port. In order to
  47.      relate the sample frame numbers to those of a particular application's
  48.      audio port, the aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeNNNNuuuummmmbbbbeeeerrrr call must be used.
  49.  
  50.      aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee uses the Unadjusted System Time (UUUUSSSSTTTT) as its timeline.
  51.      This allows it to relate to other media which also use UUUUSSSSTTTT. See the man
  52.      page for ddddmmmmGGGGeeeettttUUUUSSSSTTTT((((3333ddddmmmm)))) for more information on UST.
  53.  
  54. EEEEXXXXAAAAMMMMPPPPLLLLEEEE
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee((((3333ddddmmmm))))                                        aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.           stamp_t fn, t;
  75.           stamp_t fnd,td;
  76.           double nanosec_per_frame = 1000000000.0 / rate_in_Hz;
  77.  
  78.           /*
  79.            * Get the device sample frame number associated with the next
  80.            * audio sample frame I'm going to read or write from this port
  81.            */
  82.           alGetFrameNumber(port, &fn);
  83.  
  84.           /*
  85.            * Get some recent pair of (frame number, time) from the audio
  86.            * device to which my port is connected. time is on a timeline
  87.            * called UST which is given in nanoseconds and shared with the
  88.            * other audio devices and with other media.
  89.            */
  90.           alGetFrameTime(port, &fnd, &td);
  91.  
  92.           /*
  93.            * Calculate the UST associated with fn, the next sample frame
  94.            * we're going to read or write. Because this is signed
  95.            * arithmetic, this code works for both input and output ports.
  96.            */
  97.           t = td + (stamp_t) ((double)(fn - fnd) * nanosec_per_frame);
  98.  
  99.           /*
  100.            * If my port is not in an underflow or overflow state, I can do an
  101.            * alReadFrames or alWriteFrames here and know that t is the time
  102.            * associated with the first sample frame of the buffer I read or
  103.            * write.
  104.            */
  105.  
  106.  
  107. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  108.      Upon successful completion, aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee returns 0. Otherwise
  109.      aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee returns -1 and sets an error number which can be retrieved
  110.      with oooosssseeeerrrrrrrroooorrrr((((3333CCCC)))).
  111.  
  112.      aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee can fail for the following reasons:
  113.  
  114.      AAAALLLL____BBBBAAAADDDD____PPPPOOOORRRRTTTT
  115.           _p_o_r_t is invalid.
  116.  
  117.      AAAALLLL____BBBBAAAADDDD____NNNNOOOOTTTT____IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTEEEEDDDD
  118.           the feature is not implemented on the given machine. aaaallllGGGGeeeettttFFFFrrrraaaammmmeeeeTTTTiiiimmmmeeee
  119.           is not implemented on Indigo R4K (IP20) systems.
  120.  
  121.  
  122. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  123.      dmGetUST(3dm), alGetFrameNumber(3A), oserror(3C)
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.