WDL/nsv/nsvlib.h

   1 /*
   2   LICENSE
   3   -------
   4 Copyright 2005 Nullsoft, Inc.
   5 All rights reserved.
   6
   7 Redistribution and use in source and binary forms, with or without modification,
   8 are permitted provided that the following conditions are met:
   9
  10   * Redistributions of source code must retain the above copyright notice,
  11     this list of conditions and the following disclaimer.
  12
  13   * Redistributions in binary form must reproduce the above copyright notice,
  14     this list of conditions and the following disclaimer in the documentation
  15     and/or other materials provided with the distribution.
  16
  17   * Neither the name of Nullsoft nor the names of its contributors may be used to
  18     endorse or promote products derived from this software without specific prior written permission.
  19
  20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
  21 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
  22 FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  23 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  24 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  26 IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  27 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28
  29 */
  30 /*
  31 ** nsvlib.h - NSV file/bitstream reading/writing interface
  32 **
  33 */
  34
  35 #ifndef _NSVLIB_H_
  36 #define _NSVLIB_H_
  37
  38 /*********************************************************************
  39 ** bitstream classes
  40 */
  41
  42 #include "nsvbs.h"
  43
  44
  45 /*********************************************************************
  46 ** NSV packeting limits
  47 */
  48 #define NSV_MAX_AUDIO_LEN 0x8000  // 32kb
  49 #define NSV_MAX_VIDEO_LEN 0x80000 // 512kb
  50 #define NSV_MAX_AUX_LEN   0x8000  // 32kb for each aux stream
  51 #define NSV_MAX_AUXSTREAMS 15     // 15 aux streams maximum
  52
  53
  54 /*********************************************************************
  55 ** Constants for setting certain metadata items using addHdrMetaData()
  56 */
  57 #define METADATANAME_AUTHOR                     "Author"
  58 #define METADATANAME_TITLE                      "Title"
  59 #define METADATANAME_COPYRIGHT          "Copyright"
  60 #define METADATANAME_COMMENT            "Comment"
  61 #define METADATANAME_PROFILE            "Profile"
  62 #define METADATANAME_FILEID                     "File ID"
  63
  64 /*********************************************************************
  65 ** NSV type utility functions/macros
  66 */
  67
  68 /*
  69 ** Use NSV_MAKETYPE() to quickly make NSV audio/video/aux types.
  70 ** ex: NSV_MAKETYPE('R','G','B','A')
  71 */
  72 #define NSV_MAKETYPE(A,B,C,D) ((A) | ((B)<<8) | ((C)<<16) | ((D)<<24))
  73
  74 /*
  75 ** These functions convert types to and from strings.
  76 */
  77
  78 /* nsv_type_to_string() converts an NSV type to a string.
  79  * out must be at least 5 bytes long. If 't' is not a valid type,
  80  * then out will be set to an empty string
  81  * ex:
  82  *   char out[5];
  83  *   nsv_type_to_string(NSV_MAKETYPE('R','G','B','A'),out);
  84  *   strcmp(out,"RGBA") == 0
  85  */
  86 void nsv_type_to_string(unsigned int t, char *out);
  87
  88 /* nsv_string_to_type() converts a string to an NSV type.
  89  * Returns 0 if the type is not valid.
  90  * ex: nsv_string_to_type("RGBA") == NSV_MAKETYPE('R','G','B','A')
  91  */
  92 unsigned int nsv_string_to_type(char *in);
  93
  94
  95 /*********************************************************************
  96 ** NSV bitstream packeting/unpacketing classes
  97 */
  98
  99
 100 /* nsv_Packeter is used to packet audio/video/auxiliary data into
 101  * a bitstream.
 102  *
 103  * ex:
 104  *   nsv_Packeter p;
 105  *   nsv_OutBS bs;
 106  *   p.setVidFmt(NSV_MAKETYPE('R','G','B','A'),320,240,30.0);
 107  *   p.setAudFmt(NSV_MAKETYPE('P','C','M',' '));
 108  *   for (;;) {
 109  *     doEncodeAudioAndVideo();
 110  *     p.setSyncFrame(is_keyframe);
 111  *     p.setSyncOffset(av_sync_offset);
 112  *     p.setAudio(audio_data,audio_len);
 113  *     p.setVideo(video_data,video_len);
 114  *     p.clearAuxChannels(); // you can add aux channels if you want
 115  *     if (p.packet(bs)) error();
 116  *     int outbuflen;
 117  *     void *outbuf=bs.get(&outbuflen);
 118  *     fwrite(outbuf,outbuflen,1,fp); // write output
 119  *     bs.clear(); // clear bitstream
 120  *   }
 121  *
 122  */
 123
 124 class nsv_Packeter {
 125   public:
 126     nsv_Packeter();
 127     ~nsv_Packeter();
 128
 129     // init (per file) calls
 130     void setVidFmt(unsigned int vfmt, unsigned int w, unsigned int h, double frt);
 131     void setAudFmt(unsigned int afmt) { audfmt=afmt; }
 132
 133     // per frame calls
 134     void setSyncFrame(int is_syncframe) { is_sync_frame=is_syncframe; }
 135     void setSyncOffset(int syncoffs) { syncoffset_cur=syncoffs; }
 136     void setAudio(void *a, int a_len) { audio=a; audio_len=a_len; }
 137     void setVideo(void *v, int v_len) { video=v; video_len=v_len; }
 138     int addAuxChannel(unsigned int fmt, void *data, int data_len) // 0 on success
 139     {
 140       if (aux_used >= NSV_MAX_AUXSTREAMS) return -1;
 141       aux[aux_used]=data;
 142       aux_len[aux_used]=data_len;
 143       aux_types[aux_used]=fmt;
 144       aux_used++;
 145       return 0;
 146     }
 147     void clearAuxChannels() { aux_used=0; }
 148
 149     int packet(nsv_OutBS &bs); // returns 0 on success
 150
 151     // some utility getting functions
 152     unsigned int getAudFmt() { return audfmt; }
 153     unsigned int getVidFmt() { return vidfmt; }
 154     unsigned int getWidth() { return width; }
 155     unsigned int getHeight() { return height; }
 156     double getFrameRate() { return framerate; }
 157
 158   private:
 159     unsigned char framerate_idx;
 160     unsigned int vidfmt;
 161     unsigned int audfmt;
 162     unsigned int width;
 163     unsigned int height;
 164     double framerate;
 165     int syncoffset_cur;
 166
 167     int aux_used;
 168     void *aux[NSV_MAX_AUXSTREAMS];
 169     int aux_len[NSV_MAX_AUXSTREAMS];
 170     unsigned int aux_types[NSV_MAX_AUXSTREAMS];
 171     int is_sync_frame;
 172     void *audio;
 173     int audio_len;
 174     void *video;
 175     int video_len;
 176 };
 177
 178
 179 /* nsv_Unpacketer is used to unpacket a bitstream into audio/video/auxiliary data
 180  * to decode, use an nsv_InBS object with data, and call unpacket().
 181  * ex:
 182  *  nsv_Unpacketer up;
 183  *  nsv_InBS in;
 184  *  nsv_InBS videoout, audioout;
 185  *  up.setVideoOut(&videoout);
 186  *  up.setAudioOut(&audioout);
 187  *  for (;;) {
 188  *    int ret=up.unpacket(in);
 189  *    if (ret < 0) break; // eof
 190  *    if (ret > 0) add_data_to_bitstream(&in,ret);
 191  *    if (!ret) { // got frame
 192  *      int vl=videoout.getbits(32);
 193  *      int al=videoout.getbits(32);
 194  *      char *vd=(char*)videoout.getcurbyteptr();
 195  *      char *ad=(char*)audioout.getcurbyteptr();
 196  *      doDecode(vd,vl,ad,al);
 197  *      videoout.seek(vl*8);
 198  *      audioout.seek(al*8);
 199  *      videoout.compact(); // free memory up
 200  *      audioout.compact(); // free memory up
 201  *      in.compact(); // free memory up
 202  *    }
 203  *  }
 204  */
 205
 206 class nsv_Unpacketer {
 207   public:
 208     nsv_Unpacketer() { reset(); }
 209     ~nsv_Unpacketer() { }
 210
 211     void reset(int full=1); // if full, full reset is done.
 212                             // if not, then it is a partial reset (ie for seeking)
 213
 214     // when EOF is set, the unpacketer will fail instead of requesting more data at the
 215     // end; it will also not require that the next frame be available for sync
 216     // (normally it looks ahead to verify data)
 217     void setEof(int eof=1) { m_eof=eof; }
 218     int getEof() { return m_eof; }
 219
 220     // use these to set where the unpacketer writes the output of each stream
 221     // set to NULL to ignore output of that stream
 222
 223     void setAudioOut(nsv_InBS *output=NULL) { m_audiobs=output; }
 224     // the format of the audio data written to the output is:
 225     //   32 bits: length of frame
 226     //   ? bytes: audio data
 227     // (to read):
 228     //   int l=output->getbits(32);
 229     //   decode_audio(output->getcurbyteptr(),l);
 230     //   output->seek(l*8);
 231
 232
 233     void setVideoOut(nsv_InBS *output=NULL) { m_videobs=output; }
 234     // the format of the video data written to the output is:
 235     //   32 bits: length of frame
 236     //   ? bytes: video data
 237     // (to read):
 238     //   int l=output->getbits(32);
 239     //   decode_video(output->getcurbyteptr(),l);
 240     //   output->seek(l*8);
 241
 242     void setAuxOut(nsv_InBS *output=NULL) { m_auxbs=output; }
 243     // the format of the aux data written to the output is:
 244     //   32 bits: length of frame
 245     //   32 bits: type of aux data
 246     //   ? bytes: aux data
 247     // (to read):
 248     //   int l=output->getbits(32);
 249     //   int type=output->getbits(32);
 250     //   decode_aux(output->getcurbyteptr(),l);
 251     //   output->seek(l*8);
 252     // aux is different than audio/video in that it includes a 32 bit
 253     // type value that is not included in the length.
 254
 255
 256     // returns 0 on success, >0 on needs (at least X bytes) more data,
 257     // -1 on error (eof and no header found)
 258     int unpacket(nsv_InBS &bs);
 259
 260
 261     // do we have enough sync to determine formats/widths/heights/framerates
 262     int isValid() { return valid; }
 263
 264     // are we fully synched?
 265     int isSynched() { return synched; }
 266
 267     // get sync offset from when we first synched up
 268     signed int getSyncOffset() { return (signed int) syncoffset; }
 269
 270     // get sync offset from current frame (not usually used)
 271     signed int getCurSyncOffset() { return (signed int) syncoffset_cur; }
 272
 273     // get video, audio, width, height, framerate formats.
 274     unsigned int getVidFmt() { return vidfmt; }
 275     unsigned int getAudFmt() { return audfmt; }
 276     unsigned int getWidth() { return width; }
 277     unsigned int getHeight() { return height; }
 278     double getFrameRate() { return framerate; }
 279     unsigned char getFrameRateIdx() { return framerate_idx; }
 280
 281     // is current frame a sync frame?
 282     int isSynchFrame() { return is_sync_frame; }
 283
 284   private:
 285     nsv_InBS *m_audiobs, *m_videobs, *m_auxbs;
 286     int valid; // contents of stream info are valid for syncing
 287     int synched; // turns off anal packet checking
 288     unsigned int vidfmt;
 289     unsigned int audfmt;
 290     unsigned int width;
 291     unsigned int height;
 292     double framerate;
 293     int is_sync_frame;
 294     unsigned char framerate_idx;
 295     int syncoffset;
 296     int syncoffset_cur;
 297
 298     int m_eof;
 299 };
 300
 301
 302 /*********************************************************************
 303 ** NSV file header reading/writing functions
 304 */
 305
 306
 307 typedef struct {
 308   // header_size is the size of NSV header. nsv_writeheader() and nsv_readheader()
 309   // will set this automatically
 310   unsigned int header_size;
 311
 312   // file_lenbytes is the size of the NSV bitstream (not including the header size)
 313   // this can be 0xFFFFFFFF to signify unknown length
 314   unsigned int file_lenbytes;
 315
 316   // file_lenms is the length of the NSV bitstream in milliseconds.
 317   // this can be 0xFFFFFFFF to signify unknown length
 318   unsigned int file_lenms;
 319
 320   // metadata_len describes the length of the metadata.
 321   unsigned int metadata_len;
 322
 323   // toc_alloc describes the allocated length of the TOC (in entries).
 324   // set this to zero to use toc_size (recommended).
 325   unsigned int toc_alloc;
 326
 327   // toc_size describes the used size of the TOC (in entries)
 328   // set this to zero to disable the TOC. When using toc_ex,
 329   // this must be < toc_alloc/2 (if using nsv_writeheader, and
 330   // toc_size is too big, toc_alloc will be grown automatically.
 331   unsigned int toc_size;
 332
 333   // buffer which contains the TOC. this will be automatically
 334   // allocated when using nsv_readheader(), but you should allocate
 335   // this yourself when using nsv_writeheader()
 336   unsigned int *toc;
 337
 338   // if used, contains time pairs (in frames) for the offset. this will be
 339   // automatically allocated when using nsv_readheader(), but you should allocate
 340   // this yourself when using nsv_writeheader()
 341   // DO NOT FREE THIS VALUE IF IT WAS ALLOCATED FROM NSV_READHEADER. :)
 342   // (it is just an extension of toc, which should be freed with free())
 343   unsigned int *toc_ex;
 344
 345   // buffer which contains metadata. allocated when using nsv_readheader(),
 346   // but you should allocate this yourself when using nsv_writeheader()
 347   // note that nsv_readheader() will NULL terminate this buffer.
 348   void *metadata;
 349
 350 } nsv_fileHeader;
 351
 352 // nsv_writeheader() writes the NSV file header to the bitstream bs.
 353 // the NSV file header will be at LEAST padto bytes long (usually
 354 // you will leave padto to 0)
 355 void nsv_writeheader(nsv_OutBS &bs, nsv_fileHeader *hdr, unsigned int padto);
 356
 357 // nsv_readheader() reads an NSV file header from a bitstream bs.
 358 // if the return value is less than zero, then there is no NSV
 359 // file header in bs. if the return value is zero, the NSV file
 360 // header was succesfully read. if the return value is positive,
 361 // then at least that many more bytes are needed to decode the
 362 // header.
 363 // ex:
 364 //   nsv_InBS bs;
 365 //   nsv_fileHeader hdr;
 366 //   for (;;) {
 367 //      int ret=nsv_readheader(bs,&hdr);
 368 //      if (ret<=0) break;
 369 //      addBytesToBs(bs,ret);
 370 //   }
 371 //   if (hdr.header_size) { we_got_valid_header(&hdr); }
 372 //
 373
 374 int nsv_readheader(nsv_InBS &bs, nsv_fileHeader *hdr);
 375
 376
 377 // nsv_getmetadata() retrieves a metadata item from the metadata
 378 // block. if that item is not found, NULL is returned.
 379 // Note that the value returned by nsv_getmetadata() has been
 380 // malloc()'d, and you must free() it when you are done.
 381 // ex:
 382 //   char *v=nsv_getmetadata(hdr.metadata,"TITLE");
 383 //   if (v) printf("title=%s\n",v);
 384 //   free(v);
 385 //
 386
 387 char *nsv_getmetadata(void *metadata, char *name);
 388
 389
 390 #endif//_NSVLIB_H_