In This Topic ▼

IltmmConvert::SaveStillBitmap

Summary

Saves a snapshot from the running stream to a file, as a bitmap.

Syntax

#include "ltmm.h"

Language	Syntax
C	HRESULT IltmmConvert_SaveStillBitmap(pConvert, filename, format, quality, flags, timeout)
C++	HRESULT SaveStillBitmap(filename, format, quality, flags, timeout)

Parameters

IltmmConvert *pConvert

Pointer to an IltmmConvert interface.

BSTR filename

A character string that contains the name of the file in which to save the bitmap.

long format

Value that represents the output file format. For a list of possible values, refer to ltmmConvert_StillFormat constants.

long quality

Value that represents the compression quality. This is used only when the Format parameter is ltmmConvert_StillFormat_CMP. For a list of possible values, refer to Compression Quality Factors.

long flags

Not used. Pass 0.

long timeout

The timeout period, in milliseconds. The function will fail if it was not able to take a sample in the specified time. Use 1 to wait indefinitely until a sample is snapped

Returns

Value	Meaning
S_OK	The function was successful.
<> S_OK	An error occurred. Refer to the Error Codes or the HRESULT error codes in the DirectShow documentation.

Comments

This method blocks (does not return) until the timeout occurs or the sample is snapped.

Use the IltmmConvert::get_EnableStillCapture function to retrieve a value that indicates whether still images can be captured during conversion. Use the IltmmConvert::get_StillCaptureLimit function to retrieve the time limit, in milliseconds, for capturing a still image. Use the IltmmConvert::put_EnableStillCapture function to enable or disable the capturing of still images during conversion. Use the IltmmConvert::put_StillCaptureLimit function to set the time limit, in milliseconds, for still image capturing. Use the IltmmConvert::SaveStillBitmap function to save a snapshot from the running stream to a file, as a bitmap.

If the passed file name to the Filename parameter is NULL, then the function will return an error.

If the passed file name to the Filename parameter currently exists, then the existing file will be overwritten.

In order to save a snapshot from the running stream to a file, before calling this function the user must call IltmmConvert::put_EnableStillCapture with setting the value of newVal parameter to VARIANT_TRUE; otherwise this function will return an error.