windows-nt/Source/XPSP1/NT/multimedia/media/avi/avifile.16/avifile.d

507 lines
20 KiB
D
Raw Normal View History

2020-09-26 03:20:57 -05:00
/****************************************************************************
*
* 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 <t AVIStreamHeader> 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 <e AVISTREAMINFO.dwRate>
* to specify the time scale this stream will use.
* Dividing <e AVISTREAMINFO.dwRate> by <e AVISTREAMINFO.dwScale>
* 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 <e WAVEFORMAT.nBlockAlign> bytes of audio,
* which for PCM audio simply reduces to the sample rate.
*
* @field DWORD | dwRate | See <e AVISTREAMINFO.dwScale>.
*
* @field DWORD | dwStart | Specifies the starting time of the AVI file.
* The units are defined by the <e AVISTREAMINFO.dwRate>
* and <e AVISTREAMINFO.dwScale> 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 <e AVISTREAMINFO.dwRate>
* and <e AVISTREAMINFO.dwScale> 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 <e WAVEFORMAT.nBlockAlign>
* member of the <t WAVEFORMAT> 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 <t MainAVIHeader> 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 <e AVIFILEINFO.dwRate>
* to specify the time scale that the file as a whole will use. In addition,
* each stream can have its own time scale.
* Dividing <e AVIFILEINFO.dwRate> by <e AVIFILEINFO.dwScale>
* gives the number of samples per second.
*
* @field DWORD | dwRate | See <e AVIFILEINFO.dwScale>.
*
* @field DWORD | dwLength | Specifies the length of the AVI file.
* The units are defined by <e AVIFILEINFO.dwRate> and
* <e AVIFILEINFO.dwScale> .
*
* @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 <f EditStream> 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 <p ppsEditable> must be
* used as the source stream in the other <f EditStream> functions.
*
* Internally, this function creates tables to keep track of
* changes to a stream. The original stream is never changed
* by the <f EditStream> 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 <p pavi>.
*
* @parm LONG FAR * | plLength | Specifies the length of the data
* to be cut from the stream referenced by <p pavi>.
*
* @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 <f CreateEditableStream>
* or one of the <f EditStream> 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 <p pavi>. The
* actual starting postion is returned.
*
* @parm LONG FAR * | plLength | Specifies the length of the data
* to be copied from the stream referenced by <p pavi>.
* 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 <f CreateEditableStream>
* or one of the <f EditStream> 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 <p pstream>.
*
* @parm LONG FAR * | plPos | Specifies the starting position of the data
* to be copied from the stream referenced by <p pavi>. On returning
* from the function, <p plPos>
*
* @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 <p pstream> of the portion that will be pasted into
* stream <p pavi>.
*
* @parm LONG | lLength | Specifies the length of the data
* to be copied to the stream specified by <p pavi>. If <p lLength>
* is -1, the entire stream <p pstream> will be pasted in.
*
* @rdesc Returns zero if successful; otherwise returns an error code.
*
* @comm The stream <p pavi> must be created by <f CreateEditableStream>
* or one of the <f EditStream> functions.
*
* @xref <f CreateEditableStream> <f EditStreamCopy> <f EditStreamCut>
*
*************************************************************************/
/**************************************************************************
* @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 <f CreateEditableStream>
* or one of the <f EditStream> 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 <t AVISTREAMINFO>
* structure containing new information.
*
* @parm LONG | cbInfo | Specifies the size of the structure pointed to
* by <p lpInfo>.
*
* @rdesc Returns zero if successful; otherwise returns an error code.
*
* @comm You must fill out the <t AVISTREAMINFO> structure, including
* the members you will not use. You can use <f AVIStreamInfo> to
* to initialize the structure and then updated selected members
* with your data.
*
* This function does not change the following members:
*
* <e AVISTREAMINFO.fccType>
*
* <e AVISTREAMINFO.fccHandler>
*
* <e AVISTREAMINFO.dwFlags>
*
* <e AVISTREAMINFO.dwCaps>
*
* <e AVISTREAMINFO.dwLength>
*
* <e AVISTREAMINFO.dwInitialFrames>
*
* <e AVISTREAMINFO.dwSuggestedBufferSize>
*
* <e AVISTREAMINFO.dwSampleSize>
*
* <e AVISTREAMINFO.dwEditCount>
*
* It does change:
*
* <e AVISTREAMINFO.wPriority>
*
* <e AVISTREAMINFO.wLanguage>
*
* <e AVISTREAMINFO.dwScale>
*
* <e AVISTREAMINFO.dwRate>
*
* <e AVISTREAMINFO.dwStart>
*
* <e AVISTREAMINFO.dwQuality>
*
* <e AVISTREAMINFO.rcFrame>
*
* <e AVISTREAMINFO.szName>
*
*************************************************************************/
/**************************************************************************
* @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 <e AVISTREAMINFO.szName> member
* of the <t AVISTREAMINFO> 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.
*
*************************************************************************/