ref_iface_IVDXStreamSource_Read

VirtualDub Plugin SDK 1.2

IVDXStreamSource interface

IVDXStreamSource:: Read

Reads samples from the stream.

bool Read(sint64 start, uint32 count, void *buffer, uint32 bufferSize, uint32 *bytesRead, uint32 *samplesRead);

Parameters

start	Sample number to at which to start reading, from 0 to N where N is the number of samples in the stream. Note that the end of the stream is a valid starting point.
count	Maximum number of samples to read.
buffer	Buffer in which to place samples, or NULL to query the size of samples in the stream.
bufferSize	Maximum number of bytes to place into buffer. This parameter is ignored if buffer is NULL.
bytesRead	[out] Number of bytes actually read, or if buffer==NULL, would be read. This pointer cannot be NULL.
sampleRead	[out] Number of samples actually read, or if buffer==NULL, would be read. This pointer cannot be NULL.

Thread safety

This method is not thread-safe.

Errors

Errors may not be returned from this function (see SetError()).

Return value

True if successful, or false if no samples could be read because the buffer is not large enough to hold a single sample.

Remarks

This method is loosely modeled after the AVIStreamRead() function. A common usage pattern is to attempt to read samples with an existing buffer, and to retry the read with a larger buffer if the existing buffer is too small.

The sample count may be reduced below the requested number if it is convenient, or if some samples can be returned immediately. In particular, a video stream implementation can choose to never return more than one sample. The sample count must not be reduced to zero unless start is at the end of the stream.

It is critical that this function never write more than bufferSize bytes into the given buffer. If the buffer is not large enough to hold the requested number of samples, it should automatically reduce the number of samples read and return the actual count in *samplesRead. If the buffer cannot hold even the first sample, then Read() should return false, set *samplesRead to the number of samples that would have been read, and *bytesRead to the number of bytes required for those samples. In all cases, if *samplesRead > 0, then *bytesRead is at least as large as the first sample.

If start is at the end of the stream, then this function should return zero bytes/samples and true as the return value.

Implementations must not rely on any particular address alignment for the supplied buffer.