hvirtual/quicktime/docs/firewire.html

   1 <TITLE>Quicktime for Linux</TITLE>
   2
   3 <H1>DV INFORMATION</H1>
   4
   5 Since Quicktime supports DV, the DV library was integrated.  Originally
   6 the DV library had no front end so an abstraction to the DV library
   7 which uses Quicktime 4 Linux semantics was also written.  The front end
   8 to the integrated DV support is in <B>libdv.h</B><P>
   9
  10 <H1>THE DV_T OBJECT</H1>
  11
  12 It allows you to <P>
  13
  14 1) Decode and encode video data from a DV frame<BR>
  15 2) Decode and encode audio data from a DV frame<P>
  16
  17 DV stores audio and video in each frame.  Function calls in libdv.h
  18 handle each separately.<P>
  19
  20 <H1>DECODING</H1>
  21
  22 <B>STEP 1:</B><P>
  23
  24 #include "libdv.h" and create a new dv decoder.<P>
  25
  26 <CODE>
  27         dv_t *dv = dv_new();<P>
  28 </CODE>
  29
  30 <B>STEP 2:</B><P>
  31
  32 Read a video frame from a buffer containing one frame of DV.<P>
  33
  34 <CODE>
  35         dv_read_video(dv, output_rows, data, bytes, color_model);<P>
  36 </CODE>
  37
  38 <B>dv</B> is the dv decoding object.<P>
  39
  40 <B>output_rows</B> is an array of pointers, one pointer to each row of an
  41 output frame.  Each row must have enough memory allocated to store a
  42 row of the specified color model.  If the colormodel is planar, the
  43 first three <B>output_rows</B> are the planes and the rest is ignored.
  44 The dimensions of the frame must be determined by whatever procedure
  45 grabs the data from the device.<P>
  46
  47 <B>data</B> is the compressed data.<P>
  48
  49 <B>bytes</B> is the size of the compressed data.  This can be a #define from libdv.h.<P>
  50
  51 <B>color_model</B> is the color model to generate.  It can be almost anything
  52 from colormodels.h but not all the outputs have been tested.<P>
  53
  54 <B>STEP 3:</B><P>
  55
  56 Read an audio frame.  This procedure only works for 2 channel 16 bit
  57 encoding in the DV frame.  Call dv_read_audio for each frame to extract
  58 the audio from.<P>
  59
  60 <CODE>
  61         dv_read_audio(dv, samples, data, size, channels, bits);<P>
  62 </CODE>
  63
  64 <B>dv</B> is the dv pointer.<P>
  65
  66 <B>samples</B> is a preallocated buffer of 4096 bytes * channels *
  67 bytes per sample, an arbitrary fraction of which are going to be
  68 filled.<P>
  69
  70 <B>data</B> is the compressed DV frame.<P>
  71
  72 <B>size</B> is the number of bytes in the DV frame.<P>
  73
  74 <B>channels</B> is the number of channels libdv should store in the
  75 <B>samples</B> buffer.  The DV format allows up to 4 audio channels.
  76 If the DV frame itself has more channels than the user has allocated,
  77 they are ignored.<P>
  78
  79 This function returns the number of 16 bit, twos complement, native
  80 byte order samples deposited in *samples.<P>
  81
  82
  83
  84
  85 <B>STEP 4:</B><P>
  86
  87 Delete the dv object when finished reading frames.<P>
  88
  89 <CODE>
  90         dv_delete(dv);<P>
  91 </CODE>
  92
  93
  94
  95
  96
  97
  98
  99
 100 <H1>ENCODING</H1>
 101
 102 Creating and deleting the dv object is the same as in decoding.  This
 103 involves <B>dv_new</B> and <B>dv_delete</B>.<P>
 104
 105 <B>ENCODING VIDEO</B><P>
 106
 107 <CODE><PRE>
 108 void dv_write_video(dv_t *dv,
 109                 unsigned char *data,
 110                 unsigned char **input_rows,
 111                 int color_model,
 112                 int norm);
 113 </PRE></CODE><P>
 114
 115 Compresses the uncompressed frame in <B>input_rows</B> to the
 116 preallocated buffer pointed to by <B>data</B>.  The size of the buffer
 117 is either <B>DV_NTSC_SIZE</B> or <B>DV_PAL_SIZE</B> depending on the
 118 <B>norm</B>.<P>
 119
 120 The <B>color_model</B> can only be <B>BC_YUV422</B> or
 121 <B>BC_RGB888</B>.<P>
 122
 123 The <B>norm</B> can be <B>DV_NTSC</B> or <B>DV_PAL</B>.  The norm
 124 determines the size of the frame that must be passed to
 125 <B>input_rows</B>.  DV_NTSC requires a 720x480 frame.  DV_PAL requires
 126 a 720x576 frame.<P>
 127
 128 <B>ENCODING AUDIO</B><P>
 129
 130 After and only after encoding video into the frame, audio may be
 131 encoded.<P>
 132
 133 <CODE><PRE>
 134 int dv_write_audio(dv_t *dv,
 135                 unsigned char *data,
 136                 unsigned char *input_samples,
 137                 int max_samples,
 138                 int channels,
 139                 int bits,
 140                 int rate,
 141                 int norm);
 142 </PRE></CODE><P>
 143
 144 <B>data</B> is the same buffer previously used in the video encoding.<P>
 145
 146 <B>input_samples</B> is interleaved, 16 bit, twos complement, native
 147 byte order, audio in the number of channels specified by
 148 <B>channels</B>.<P>
 149
 150 <B>max_samples</B> is the number of samples in the <B>input_samples</B>
 151 buffer.  There should be at least 4096 samples in the buffer.<P>
 152
 153 <B>channels</B> specifies the number of channels in the interleaved
 154 buffer.  This matches the number of channels encoded in the DV frame.
 155 The DV standard allows 2 to 4 channels, depending on <B>bits</B> and
 156 <B>rate</B>.<P>
 157
 158 <B>bits, rate</B> specify the encoding of the audio in the DV frame.<P>
 159
 160 The <B>norm</B> can be <B>DV_NTSC</B> or <B>DV_PAL</B>.<P>
 161
 162 This function returns the number of samples actually encoded in the
 163 frame.  This is usually less than the <B>max_samples</B> argument but
 164 is not constant.  It is up to the user to reuse the remaining samples
 165 in the next frame.<P>
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175