/**************************************************************************** * * AVIFILE.D * * Autodoc for the AVI clipboard and editing functions. * ***************************************************************************/ // // Defines for the dwFlags field of the AVICOMPRESSOPTIONS struct // #define AVICOMPRESSF_INTERLEAVE 0x00000001 #define AVICOMPRESSF_DATARATE 0x00000002 #define AVICOMPRESSF_KEYFRAMES 0x00000004 #define AVICOMPRESSF_VALID 0x00000008 // has valid data? STDAPI_(void) AVIFileInit(void); // Call this first! STDAPI_(void) AVIFileExit(void); #define MAKE_AVIERR(error) MAKE_SCODE(SEVERITY_ERROR, FACILITY_ITF, 0x4000 + error) #define AVIERR_UNSUPPORTED MAKE_AVIERR(101) #define AVIERR_BADFORMAT MAKE_AVIERR(102) #define AVIERR_MEMORY MAKE_AVIERR(103) #define AVIERR_INTERNAL MAKE_AVIERR(104) #define AVIERR_BADFLAGS MAKE_AVIERR(105) #define AVIERR_BADPARAM MAKE_AVIERR(106) #define AVIERR_BADSIZE MAKE_AVIERR(107) #define AVIERR_BADHANDLE MAKE_AVIERR(108) #define AVIERR_FILEREAD MAKE_AVIERR(109) #define AVIERR_FILEWRITE MAKE_AVIERR(110) #define AVIERR_FILEOPEN MAKE_AVIERR(111) #define AVIERR_COMPRESSOR MAKE_AVIERR(112) #define AVIERR_NOCOMPRESSOR MAKE_AVIERR(113) #define AVIERR_READONLY MAKE_AVIERR(114) #define AVIERR_NODATA MAKE_AVIERR(115) #define AVIERR_BUFFERTOOSMALL MAKE_AVIERR(116) #define AVIERR_CANTCOMPRESS MAKE_AVIERR(117) #define AVIERR_USERABORT MAKE_AVIERR(198) #define AVIERR_ERROR MAKE_AVIERR(199) #endif /***************************************************************************** * @doc EXTERNAL AVISTREAMINFO * * @types AVISTREAMINFO | This structure contains information * for a single stream. It is similar to, but not * identical to found in AVI files. * * @field DWORD | fccType | Specifies a four-character code * indicating the stream type. The following * constants have been defined for the data commonly * found in AVI streams: * * @flag streamtypeAUDIO | Indicates an audio stream. * @flag streamtypeMIDI | Indicates a MIDI stream. * @flag streamtypeTEXT | Indicates a text stream. * @flag streamtypeVIDEO | Indicates a video stream. * * @field DWORD | fccHandler | For a video stream, specifies the * four-character code of the compressor handler that * will compress this stream when it is saved * (For example, mmioFOURCC('M','S','V','C')). * This member is not used for audio streams. * * @field DWORD | dwFlags | Specifies any applicable flags. The bits * in the high-order word of these flags are specific * to the type of data contained in the stream. The following * flags are defined: * * @flag AVISF_DISABLED | Indicates this stream should not be enabled by default. * @flag AVISF_VIDEO_PALCHANGES | Indicates this video stream contains * palette changes. This flag warns the playback software that it will need * to animate the palette. * * @field DWORD | dwCaps | Specifies capability flags. This is currently * unused. * * @field WORD | wPriority | Specifies the priority of the stream. * * @field WORD | wLanguage | Specifies the language of the stream. * * @field DWORD | dwScale | This member is used with * to specify the time scale this stream will use. * Dividing by * gives the number of samples per second. * For video streams, this rate should be the frame rate. * For audio streams, this rate should correspond to the time * needed for bytes of audio, * which for PCM audio simply reduces to the sample rate. * * @field DWORD | dwRate | See . * * @field DWORD | dwStart | Specifies the starting time of the AVI file. * The units are defined by the * and members of this structure. * Normally, this is zero, but it can specify a * delay time for a stream which does not start concurrently * with the file. * Note: The 1.0 release of the AVI tools does not support * a non-zero starting time. * * @field DWORD | dwLength | Specifies the length of this stream. * The units are defined by the * and members of this structure. * * @field DWORD | dwInitialFrames | Specifies how far audio * data is skewed ahead of the video frames in * interleaved files. Typically, this is about 0.75 seconds. * * @field DWORD | dwSuggestedBufferSize | Suggests how large a buffer * should be used to read this stream. Typically, this * contains a value corresponding to the largest chunk * present in the stream. Using the correct buffer size * makes playback more efficient. Use zero if you * do not know the correct buffer size. * * @field DWORD | dwQuality | Specifies an indicator of the quality of * the data in the stream. Quality is represented as a number * between 0 and 10000. For compressed data, this typically represents * the value of the quality parameter passed to the compression software. * If set to -1, drivers use the default quality value. * * @field DWORD | dwSampleSize | Specifies the size of a single * sample of data. This is set to zero if the samples can * vary in size. If this number is non-zero, then multiple * samples of data can be grouped into a single chunk * within the file. If it is zero, each sample of data (such as a * video frame) must be in a separate chunk. * * For video streams, this number is typically zero, although it can * be non-zero if all video frames are the same size. For audio streams, * this number should be the same as the * member of the structure describing the audio. * * @field RECT | rcFrame | Specifies the dimensions of the destination * rectangle for the video. The coordinates rpresent the * the upper-left corner, and the height and width. * * @field DWORD | dwEditCount | Specifies the number of times the * stream has been edited. The stream handler maintains this * count. * * @field DWORD | dwFormatChangeCount | Specifies the number of times * stream format has changed. The stream handler maintains this * count. * * @field char | szName[64] | Specifies a zero-terminated string containing * a description of the stream. * ***************************************************************************/ /***************************************************************************** * @doc EXTERNAL AVIFILEINFO * * @types AVIFILEINFO | This structure contains global information * for an entire AVI file. It is similar to, but not * identical to found in AVI files. * * @field DWORD | dwMaxBytesPerSec | Specifies the approximate maximum * data rate of file. * * @field DWORD | dwFlags | Specifies any applicable flags. * The following flags are defined: * * @flag AVIF_HASINDEX | Indicates the AVI file has * an index at the end of the file. For good performance, * all AVI files should contain an index. * @flag AVIF_MUSTUSEINDEX | Indicates that the index, rather than the * physical ordering of the chunks in the file, should be used to * determine the order of presentation of the data. For example, this * could be used for creating a list frames for editing. * @flag AVIF_ISINTERLEAVED | Indicates the AVI file is interleaved. * @flag AVIF_WASCAPTUREFILE | Indicates the AVI file is a specially * allocated file used for capturing real-time video. Applications * should warn the user before writing over a file with this flag set * because the user probably defragmented this file. * @flag AVIF_COPYRIGHTED | Indicates the AVI file contains copyrighted * data and software. When this flag is used, software should * not permit the data to be duplicated. * * @field DWORD | dwCaps | Specifies capability flags. This is currently unused. * * @field DWORD | dwStreams | Specifies the number of streams in the file. * For example, a file with audio and video has two streams. * * @field DWORD | dwSuggestedBufferSize | Specifies the suggested buffer * size for reading the file. Generally, this size should be large * enough to contain the largest chunk in the file. If set to zero, or * if it is too small, the playback software will have to reallocate * memory during playback which will reduce performance. * * For an interleaved file, this buffer size should be large enough to read * an entire record and not just a chunk. * * @field DWORD | dwWidth | Specifies the width of the AVI file in pixels. * * @field DWORD | dwHeight | Specifies the height of the AVI file in pixels. * * @field DWORD | dwScale | This field is used with * to specify the time scale that the file as a whole will use. In addition, * each stream can have its own time scale. * Dividing by * gives the number of samples per second. * * @field DWORD | dwRate | See . * * @field DWORD | dwLength | Specifies the length of the AVI file. * The units are defined by and * . * * @field DWORD | dwEditCount | Specifies the number of streams that have * been added or deleted. * * @field char | szFileType[64] | Specifies a zero-terminated string * containing descriptive information for the file type. * ***************************************************************************/ /************************************************************************** * @doc EXTERNAL AVIPutFileOnClipboard * * @api STDAPI | AVIPutFileOnClipboard | Copies an AVI file onto the Clipboard. * * @parm PAVIFILE | pf | Specifies a handle to an open AVI file. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm This function will also copy data with the CF_DIB and * CF_WAVE Clipboard flags onto the Clipboard. * *************************************************************************/ /************************************************************************** * @doc EXTERNAL AVIGetFromClipboard * * @api STDAPI | AVIGetFromClipboard | Copies an AVI file from the Clipboard. * * @parm PAVIFILE * | lppf | Specifies the location used to return * the handle created for the AVI file. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm This function will also copy data with the CF_DIB or CF_WAVE * Clipboard flags. * *************************************************************************/ /************************************************************************** * @doc EXTERNAL AVIClearClipboard * * @api STDAPI | AVIClearClipboard | Clears an AVI file from the Clipboard. * Use this function before ending your application to clear the * contents of the Clipboard. * * @rdesc Returns zero if successful; otherwise returns an error code. * *************************************************************************/ /************************************************************************** * @doc EXTERNAL CreateEditableStream * * @api STDAPI | CreateEditableStream | Creates an editable stream. * Use this function before using other functions. * * @parm PAVISTREAM FAR * | ppsEditable | Specifies a pointer to the location * used to return the handle to the new stream. * * @parm PAVISTREAM | psSource | Specifies a handle to the open stream * used as the source of data. Specify NULL to create * an empty editable string that you can copy and paste data * into. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm The stream pointer returned in

must be * used as the source stream in the other functions. * * Internally, this function creates tables to keep track of * changes to a stream. The original stream is never changed * by the functions. The stream pointer * created by this function can be used in any AVIFile function * that accepts stream pointers. You can use this function on * the same stream multiple times. A copy of a stream is not * affected by changes in another copy. * *************************************************************************/ /************************************************************************** * @doc EXTERNAL EditStreamCut * * @api STDAPI | EditStreamCut | Deletes an editable * stream (or a portion of it) and copies it into a temporary stream. * * @parm PAVISTREAM | pavi | Specifies a handle to the editable stream used * as the source of the data. * * @parm LONG FAR * | plStart | Specifies the starting position of the data * to be cut from the stream referenced by

. * * @parm LONG FAR * | plLength | Specifies the length of the data * to be cut from the stream referenced by

. * * @parm PAVISTREAM FAR * | ppResult | Specifies a pointer to the location * used to return the handle created for the new stream. * * @comm The editable stream must be created by * or one of the functions. * * The temporary stream is an editable stream and * can be treated as any other AVI stream. * * @rdesc Returns zero if successful; otherwise returns an error code. * *************************************************************************/ /************************************************************************** * @doc EXTERNAL EditStreamCopy * * @api STDAPI | EditStreamCopy | Copies an editable * stream (or a portion of it) into a temporary stream. * * @parm PAVISTREAM | pavi | Specifies a handle to an editable stream used * as the source of the data. * * @parm LONG FAR * | plStart | Specifies the starting position of the data * to be copied from the stream referenced by

. The * actual starting postion is returned. * * @parm LONG FAR * | plLength | Specifies the length of the data * to be copied from the stream referenced by

. * The actual length of the copied data is returned. * * @parm PAVISTREAM FAR * | ppResult | Specifies a pointer to the location * used to return the handle created for the new stream. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm The editable stream must be created by * or one of the functions. * * The temporary stream can be treated as any other AVI stream. * *************************************************************************/ /************************************************************************** * @doc EXTERNAL EditStreamPaste * * @api STDAPI | EditStreamPaste | Copies a stream (or a portion of it) into * another stream. * * @parm PAVISTREAM | pavi | Specifies a handle to a editable stream * used as the destination of data from the stream specified * for

. * * @parm LONG FAR * | plPos | Specifies the starting position of the data * to be copied from the stream referenced by

. On returning * from the function,

* * @parm LONG FAR * | plLength | Specifies a pointer to where the length * of the data pasted in will be returned. * * @parm PAVISTREAM | pstream | Specifies a handle to a stream used * as the source of the data. This stream does not need to * be an editable stream. * * @parm LONG | lStart | Specifies the starting position within the stream * referenced by

of the portion that will be pasted into * stream

. * * @parm LONG | lLength | Specifies the length of the data * to be copied to the stream specified by

. If

* is -1, the entire stream

will be pasted in. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm The stream

must be created by * or one of the functions. * * @xref * *************************************************************************/ /************************************************************************** * @doc EXTERNAL EditStreamClone * * @api STDAPI | EditStreamClone | Creates a duplicate editable * stream. * * @parm PAVISTREAM | pavi | Specifies a handle to an editable stream. * * @parm PAVISTREAM FAR * | ppResult | Specifies the location used * to return the handle to the stream created. This stream is * an editable stream. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm The editable stream must be created by * or one of the functions. * * The stream created can be treated as any other AVI stream. * * You can use this function as the basis of an "undo" feature. * You can also use this function to create a stream copied to * the clipboard. * *************************************************************************/ /************************************************************************** * @doc EXTERNAL EditStreamSetInfo * * @api SDTAPI | EditStreamSetInfo | Changes characteristics of an * editable stream. * * @parm PAVISTREAM | pavi | Specifies a handle to an open stream. * * @parm AVISTREAMINFO FAR * | lpInfo | Points to an * structure containing new information. * * @parm LONG | cbInfo | Specifies the size of the structure pointed to * by

. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm You must fill out the structure, including * the members you will not use. You can use to * to initialize the structure and then updated selected members * with your data. * * This function does not change the following members: * * * * * * * * * * * * * * * * * * * * It does change: * * * * * * * * * * * * * * * * * *************************************************************************/ /************************************************************************** * @doc EXTERNAL EditStreamSetName * * @api SDTAPI | EditStreamSetName | Assigns a descriptive string to a stream. * * @parm PAVISTREAM | pavi | Specifies a handle to an open stream. * * @parm LPCSTR | lpszName | Specifies a zero-terminated string * containing the description of the stream. * * @rdesc Returns zero if successful; otherwise returns an error code. * * @comm This function updates the member * of the structure. * *************************************************************************/ STDAPI AVIMakeStreamFromClipboard(UINT cfFormat, HANDLE hGlobal, PAVISTREAM FAR *ppstream); /************************************************************************** * @doc EXTERNAL AVIMakeStreamFromClipboard * * @api SDTAPI | AVIMakeStreamFromClipboard | Creates a stream from a * stream on the Clipboard. * * @parm UINT | cfFormat | Specifies a Clipboard flag. * * @parm HANDLE | hGlobal | Specifies a handle to an open stream. * * @parm PAVISTREAM FAR * | ppstream | Specifies a handle to an open stream. * * @rdesc Returns zero if successful; otherwise returns an error code. * *************************************************************************/