Applies to: desktop apps | Metro style apps
Represents a byte stream from some data source, which might be a local file, a network file, or some other source. The
The following functions return
A byte stream for a media souce can be opened with read access. A byte stream for an archive media sink should be opened with both read and write access. (Read access may be required, because the archive sink might need to read portions of the file as it writes.)
Some implementations of this interface also expose one or more of the following interfaces:
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents a byte stream from some data source, which might be a local file, a network file, or some other source. The
The following functions return
A byte stream for a media souce can be opened with read access. A byte stream for an archive media sink should be opened with both read and write access. (Read access may be required, because the archive sink might need to read portions of the file as it writes.)
Some implementations of this interface also expose one or more of the following interfaces:
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Reads data from the stream.
Pointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
This method reads at most cb bytes from the current position in the stream and copies them into the buffer provided by the caller. The number of bytes that were read is returned in the pcbRead parameter. The method does not return an error code on reaching the end of the file, so the application should check the value in pcbRead after the method returns.
This method is synchronous. It blocks until the read operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous read operation from the stream.
Pointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been read into the buffer, the callback object's
Do not read from, write to, free, or reallocate the buffer while an asynchronous read is pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous read operation.
Pointer to the
Call this method after the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Writes data to the stream.
Pointer to a buffer that contains the data to write.
Size of the buffer in bytes.
Receives the number of bytes that are written.
If this method succeeds, it returns
This method writes the contents of the pb buffer to the stream, starting at the current stream position. The number of bytes that were written is returned in the pcbWritten parameter.
This method is synchronous. It blocks until the write operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous write operation to the stream.
Pointer to a buffer containing the data to write.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been written to the stream, the callback object's
Do not reallocate, free, or write to the buffer while an asynchronous write is still pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous write operation.
Pointer to the
Call this method when the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Moves the current position in the stream by a specified offset.
Specifies the origin of the seek as a member of the
Specifies the new position, as a byte offset from the seek origin.
Specifies zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| All pending I/O requests are canceled after the seek request completes successfully. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Clears any internal buffers used by the stream. If you are writing to the stream, the buffered data is written to the underlying file or device.
If this method succeeds, it returns
If the byte stream is read-only, this method has no effect.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Closes the stream and releases any resources associated with the stream, such as sockets or file handles. This method also cancels any pending asynchronous I/O requests.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the byte stream.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the stream.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current read or write position in the stream.
The methods that update the current position are Read, BeginRead, Write, BeginWrite, SetCurrentPosition, and Seek.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the current position has reached the end of the stream.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Reads data from the stream.
Pointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
This method reads at most cb bytes from the current position in the stream and copies them into the buffer provided by the caller. The number of bytes that were read is returned in the pcbRead parameter. The method does not return an error code on reaching the end of the file, so the application should check the value in pcbRead after the method returns.
This method is synchronous. It blocks until the read operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous read operation from the stream.
Pointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been read into the buffer, the callback object's
Do not read from, write to, free, or reallocate the buffer while an asynchronous read is pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous read operation.
Pointer to the
Call this method after the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Writes data to the stream.
Pointer to a buffer that contains the data to write.
Size of the buffer in bytes.
This method writes the contents of the pb buffer to the stream, starting at the current stream position. The number of bytes that were written is returned in the pcbWritten parameter.
This method is synchronous. It blocks until the write operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous write operation to the stream.
Pointer to a buffer containing the data to write.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been written to the stream, the callback object's
Do not reallocate, free, or write to the buffer while an asynchronous write is still pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous write operation.
Pointer to the
Call this method when the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Moves the current position in the stream by a specified offset.
Specifies the origin of the seek as a member of the
Specifies the new position, as a byte offset from the seek origin.
Specifies zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| All pending I/O requests are canceled after the seek request completes successfully. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Clears any internal buffers used by the stream. If you are writing to the stream, the buffered data is written to the underlying file or device.
If this method succeeds, it returns
If the byte stream is read-only, this method has no effect.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Closes the stream and releases any resources associated with the stream, such as sockets or file handles. This method also cancels any pending asynchronous I/O requests.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the byte stream.
Receives a bitwise OR of zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| The byte stream can be read. |
| The byte stream can be written to. |
| The byte stream can be seeked. |
| The byte stream is from a remote source, such as a network. |
| The byte stream represents a file directory. |
| Seeking within this stream might be slow. For example, the byte stream might download from a network. |
| The byte stream is currently downloading data to a local cache. Read operations on the byte stream might take longer until the data is completely downloaded. This flag is cleared after all of the data has been downloaded. If the MFBYTESTREAM_HAS_SLOW_SEEK flag is also set, it means the byte stream must download the entire file sequentially. Otherwise, the byte stream can respond to seek requests by restarting the download from a new point in the stream. |
| Another thread or process can open this byte stream for writing. If this flag is present, the length of thebyte stream could change while it is being read. This flag can affect the behavior of byte-stream handlers. For more information, see MF_BYTESTREAMHANDLER_ACCEPTS_SHARE_WRITE. Note??Requires Windows?7 or later. |
?
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the stream.
Receives the length of the stream, in bytes. If the length is unknown, this value is -1.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the length of the stream.
Length of the stream in bytes.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current read or write position in the stream.
Receives the current position, in bytes.
If this method succeeds, it returns
The methods that update the current position are Read, BeginRead, Write, BeginWrite, SetCurrentPosition, and Seek.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the current read or write position.
New position in the stream, as a byte offset from the start of the stream.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
?
If the new position is larger than the length of the stream, the method returns E_INVALIDARG.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the current position has reached the end of the stream.
Receives the value TRUE if the end of the stream has been reached, or
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Reads data from the stream.
Pointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Receives the number of bytes that are copied into the buffer. This parameter cannot be
If this method succeeds, it returns
This method reads at most cb bytes from the current position in the stream and copies them into the buffer provided by the caller. The number of bytes that were read is returned in the pcbRead parameter. The method does not return an error code on reaching the end of the file, so the application should check the value in pcbRead after the method returns.
This method is synchronous. It blocks until the read operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous read operation from the stream.
Pointer to a buffer that receives the data. The caller must allocate the buffer.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been read into the buffer, the callback object's
Do not read from, write to, free, or reallocate the buffer while an asynchronous read is pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous read operation.
Pointer to the
Receives the number of bytes that were read.
If this method succeeds, it returns
Call this method after the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Writes data to the stream.
Pointer to a buffer that contains the data to write.
Size of the buffer in bytes.
Receives the number of bytes that are written.
If this method succeeds, it returns
This method writes the contents of the pb buffer to the stream, starting at the current stream position. The number of bytes that were written is returned in the pcbWritten parameter.
This method is synchronous. It blocks until the write operation completes.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous write operation to the stream.
Pointer to a buffer containing the data to write.
Size of the buffer in bytes.
Pointer to the
Pointer to the
If this method succeeds, it returns
When all of the data has been written to the stream, the callback object's
Do not reallocate, free, or write to the buffer while an asynchronous write is still pending.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous write operation.
Pointer to the
Receives the number of bytes that were written.
If this method succeeds, it returns
Call this method when the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Moves the current position in the stream by a specified offset.
Specifies the origin of the seek as a member of the
Specifies the new position, as a byte offset from the seek origin.
Specifies zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| All pending I/O requests are canceled after the seek request completes successfully. |
?
Receives the new position after the seek.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Clears any internal buffers used by the stream. If you are writing to the stream, the buffered data is written to the underlying file or device.
If this method succeeds, it returns
If the byte stream is read-only, this method has no effect.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Closes the stream and releases any resources associated with the stream, such as sockets or file handles. This method also cancels any pending asynchronous I/O requests.
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the characteristics of the byte stream.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the stream.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the current read or write position in the stream.
The methods that update the current position are Read, BeginRead, Write, BeginWrite, SetCurrentPosition, and Seek.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the current position has reached the end of the stream.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gives the caller exclusive access to the Microsoft Direct3D device.
When you are done using the Direct3D device, call
If the method returns MF_E_DXGI_NEW_VIDEO_DEVICE, call
If fBlock is TRUE, this method can potentially deadlock. For example, it will deadlock if a thread calls LockDevice and then waits on another thread that calls LockDevice. It will also deadlock if a thread calls LockDevice twice without calling UnlockDevice in between.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an instance of the Microsoft DirectX Graphics Infrastructure (DXGI) Device Manager.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the Microsoft Direct3D device or notifies the device manager that the Direct3D device was reset.
A reference to the
When you first create the DXGI Device Manager, call this method with a reference to the Direct3D device. (The device manager does not create the device; the caller must provide the device reference initially.) Also call this method if the Direct3D device becomes lost and you need to reset the device or create a new device.
The resetToken parameter ensures that only the component that originally created the device manager can invalidate the current device.
If this method succeeds, all open device handles become invalid.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unlocks the Microsoft Direct3D device.
A handle to the Direct3D device. To get the device handle, call
Call this method to release the device after calling
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Closes a Microsoft Direct3D device handle.
A handle to the Direct3D device.
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| The specified handle is not a Direct3D device handle. |
?
Call this method to release a device handle that was retrieved by the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries the Microsoft Direct3D device for an interface.
A handle to the Direct3D device. To get the device handle, call
The interface identifier (IID) of the requested interface. The Direct3D device supports the following interfaces:
Receives a reference to the requested interface. The caller must release the interface.
If the method returns MF_E_DXGI_NEW_VIDEO_DEVICE, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gives the caller exclusive access to the Microsoft Direct3D device.
A handle to the Direct3D device. To get the device handle, call
The interface identifier (IID) of the requested interface. The Direct3D device will support the following interfaces:
Specifies whether to wait for the device lock. If the device is already locked and this parameter is TRUE, the method blocks until the device is unlocked. Otherwise, if the device is locked and this parameter is
Receives a reference to the requested interface. The caller must release the interface.
When you are done using the Direct3D device, call
If the method returns MF_E_DXGI_NEW_VIDEO_DEVICE, call
If fBlock is TRUE, this method can potentially deadlock. For example, it will deadlock if a thread calls LockDevice and then waits on another thread that calls LockDevice. It will also deadlock if a thread calls LockDevice twice without calling UnlockDevice in between.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a handle to the Microsoft Direct3D device.
Receives the device handle.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the Microsoft Direct3D device or notifies the device manager that the Direct3D device was reset.
A reference to the
The token that was received in the pResetToken parameter of the
If this method succeeds, it returns
When you first create the DXGI Device Manager, call this method with a reference to the Direct3D device. (The device manager does not create the device; the caller must provide the device reference initially.) Also call this method if the Direct3D device becomes lost and you need to reset the device or create a new device.
The resetToken parameter ensures that only the component that originally created the device manager can invalidate the current device.
If this method succeeds, all open device handles become invalid.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Tests whether a Microsoft Direct3D device handle is valid.
A handle to the Direct3D device. To get the device handle, call
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| The specified handle is not a Direct3D device handle. |
| The device handle is invalid. |
?
If the method returns MF_E_DXGI_NEW_VIDEO_DEVICE, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unlocks the Microsoft Direct3D device.
A handle to the Direct3D device. To get the device handle, call
Reserved.
If this method succeeds, it returns
Call this method to release the device after calling
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an instance of the Media Engine.
Before using this interface, call CoInitializeEx and
To get a reference to this interface, call CoCreateInstance. The class identifier is
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a new instance of the Media Engine.
A bitwise OR of zero or more flags from the
A reference to the
This parameter specifies configuration attributes for the Media Engine. Call
Receives a reference to the
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| A required attribute was missing from pAttr, or an invalid combination of attributes was used. |
?
Before calling this method, call
The Media Engine supports three distinct modes:
| Mode | Description |
|---|---|
| Frame-server mode | In this mode, the Media Engine delivers uncompressed video frames to the application. The application is responsible for displaying each frame, using Microsoft Direct3D or any other rendering technique. The Media Engine renders the audio; the application is not responsible for audio rendering. Frame-server mode is the default mode. |
| Rendering mode | In this mode, the Media Engine renders both audio and video. The video is rendered to a window or Microsoft DirectComposition visual provided by the application. To enable rendering mode, set either the MF_MEDIA_ENGINE_PLAYBACK_HWND attribute or the MF_MEDIA_ENGINE_PLAYBACK_VISUAL attribute. |
| Audio mode | In this mode, the Media Engine renders audio only, with no video. To enable audio mode, set the |
?
Intialization AttributesThe following attributes are defined for the pAttr parameter. Some are required, and some are optional, depending on the mode you want.
| Feature | Attributes | Frame Server Mode | Rendering Mode | Audio Mode |
|---|---|---|---|---|
| Event callback | | Required. | Required. | Required. |
| Render target | One of the following:
These attributes are mutually exclusive. Setting either of these attributes puts the Media Engine into rendering mode. | Do not set. | Required. | Do not set. |
| Direct3D format | | Required. | Optional. | Do not set. |
| Microsoft DirectX Graphics Infrastructure (DXGI) device manager | | Optional. | Optional. | Do not set. |
| Media Engine extensions | | Optional. | Optional. | Optional. |
| Content protection | Any of the following:
| Optional. | Optional. | Optional. |
| Audio playback | Any of the following: | Optional. | Optional. | Optional. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a time range object.
Receives a reference to the
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a media error object.
Receives a reference to the
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Extends the
The
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Copies the current video frame to a DXGI surface or WIC bitmap.
In frame-server mode, call this method to blit the video frame to a DXGI or WIC surface. The application can call this method at any time after the Media Engine loads a video resource. Typically, however, the application calls
The Media Engine scales and letterboxes the video to fit the destination rectangle. It fills the letterbox area with the border color.
For protected content, call the IMFMediaEngineProtectedContent::TransferVideoFrame method instead of this method.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the most recent error status.
Receives either a reference to the
If this method succeeds, it returns
This method returns the last error status, if any, that resulted from loading the media source. If there has not been an error, ppError receives the value
This method corresponds to the error attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the current error code.
The error code, as an
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets a list of media sources.
A reference to the
If this method succeeds, it returns
This method corresponds to adding a list of source elements to a media element in HTML5.
The Media Engine tries to load each item in the pSrcElements list, until it finds one that loads successfully. After this method is called, the application can use the
This method completes asynchronously. When the operation starts, the Media Engine sends an
If the Media Engine is unable to load a URL, it sends an
For more information about event handling in the Media Engine, see
If the application also calls
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the URL of a media resource.
The URL of the media resource.
If this method succeeds, it returns
This method corresponds to setting the src attribute of the HTMLMediaElement interface in HTML5.
The URL specified by this method takes precedence over media resources specified in the
This method asynchronously loads the URL. When the operation starts, the Media Engine sends an
If the Media Engine is unable to load the URL, the Media Engine sends an
For more information about event handling in the Media Engine, see
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the URL of the current media resource, or an empty string if no media resource is present.
Receives a BSTR that contains the URL of the current media resource. If there is no media resource, ppUrl receives an empty string. The caller must free the BSTR by calling SysFreeString.
If this method succeeds, it returns
This method corresponds to the currentSrc attribute of the HTMLMediaElement interface in HTML5.
Initially, the current media resource is empty. It is updated when the Media Engine performs the resource selection algorithm.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the current network state of the media engine.
Returns an
This method corresponds to the networkState attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the preload flag.
Returns an
This method corresponds to the preload attribute of the HTMLMediaElement interface in HTML5. The value is a hint to the user-agent whether to preload the media resource.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the preload flag.
An
If this method succeeds, it returns
This method corresponds to setting the preload attribute of the HTMLMediaElement interface in HTML5. The value is a hint to the user-agent whether to preload the media resource.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries how much resource data the media engine has buffered.
Receives a reference to the
If this method succeeds, it returns
This method corresponds to the buffered attribute of the HTMLMediaElement interface in HTML5.
The returned
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Loads the current media source.
If this method succeeds, it returns
The main purpose of this method is to reload a list of source elements after updating the list. For more information, see SetSourceElements. Otherwise, calling this method is generally not required. To load a new media source, call
The Load method explictly invokes the Media Engine's media resource loading algorithm. Before calling this method, you must set the media resource by calling
This method completes asynchronously. When the Load operation starts, the Media Engine sends an
If the Media Engine is unable to load the file, the Media Engine sends an
For more information about event handling in the Media Engine, see
This method corresponds to the load method of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries how likely it is that the Media Engine can play a specified type of media resource.
A string that contains a MIME type with an optional codecs parameter, as defined in RFC 4281.
Receives an
If this method succeeds, it returns
This method corresponds to the canPlayType attribute of the HTMLMediaElement interface in HTML5.
The canPlayType attribute defines the following values.
| Value | Description |
|---|---|
| "" (empty string) | The user-agent cannot play the resource, or the resource type is "application/octet-stream". |
| "probably" | The user-agent probably can play the resource. |
| "maybe" | Neither of the previous values applies. |
?
The value "probably" is used because a MIME type for a media resource is generally not a complete description of the resource. For example, "video/mp4" specifies an MP4 file with video, but does not describe the codec. Even with the optional codecs parameter, the MIME type omits some information, such as the actual coded bit rate. Therefore, it is usually impossible to be certain that playback is possible until the actual media resource is opened.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the ready state, which indicates whether the current media resource can be rendered.
Returns an
This method corresponds to the readyState attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the Media Engine is currently seeking to a new playback position.
Returns TRUE if the Media Engine is seeking, or
This method corresponds to the seeking attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the current playback position.
Returns the playback position, in seconds.
This method corresponds to the currentTime attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Seeks to a new playback position.
The new playback position, in seconds.
If this method succeeds, it returns
This method corresponds to setting the currentTime attribute of the HTMLMediaElement interface in HTML5.
The method completes asynchronously. When the seek operation starts, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the initial playback position.
Returns the initial playback position, in seconds.
This method corresponds to the initialTime attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the duration of the media resource.
Returns the duration, in seconds. If no media data is available, the method returns not-a-number (NaN). If the duration is unbounded, the method returns an infinite value.
This method corresponds to the duration attribute of the HTMLMediaElement interface in HTML5.
If the duration changes, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether playback is currently paused.
Returns TRUE if playback is paused, or
This method corresponds to the paused attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the default playback rate.
Returns the default playback rate, as a multiple of normal (1?) playback. A negative value indicates reverse playback.
This method corresponds to getting the defaultPlaybackRate attribute of the HTMLMediaElement interface in HTML5.
The default playback rate is used for the next call to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the default playback rate.
The default playback rate, as a multiple of normal (1?) playback. A negative value indicates reverse playback.
If this method succeeds, it returns
This method corresponds to setting the defaultPlaybackRate attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the current playback rate.
Returns the playback rate, as a multiple of normal (1?) playback. A negative value indicates reverse playback.
This method corresponds to getting the playbackRate attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the current playback rate.
The playback rate, as a multiple of normal (1?) playback. A negative value indicates reverse playback.
If this method succeeds, it returns
This method corresponds to setting the playbackRate attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the time ranges that have been rendered.
Receives a reference to the
If this method succeeds, it returns
This method corresponds to the played attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the time ranges to which the Media Engine can currently seek.
Receives a reference to the
If this method succeeds, it returns
This method corresponds to the seekable attribute of the HTMLMediaElement interface in HTML5.
To find out whether the media source supports seeking, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether playback has ended.
Returns TRUE if the direction of playback is forward and playback has reached the end of the media resource. Returns
This method corresponds to the ended attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the Media Engine automatically begins playback.
Returns TRUE if the Media Engine automatically begins playback, or
This method corresponds to the autoplay attribute of the HTMLMediaElement interface in HTML5.
If this method returns TRUE, playback begins automatically after the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies whether the Media Engine automatically begins playback.
If TRUE, the Media Engine automatically begins playback after it loads a media source. Otherwise, playback does not begin until the application calls
If this method succeeds, it returns
This method corresponds to setting the autoplay attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the Media Engine will loop playback.
Returns TRUE if looping is enabled, or
This method corresponds to getting the loop attribute of the HTMLMediaElement interface in HTML5.
If looping is enabled, the Media Engine seeks to the start of the content when playback reaches the end.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies whether the Media Engine loops playback.
Specify TRUE to enable looping, or
If this method succeeds, it returns
If Loop is TRUE, playback loops back to the beginning when it reaches the end of the source.
This method corresponds to setting the loop attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Starts playback.
If this method succeeds, it returns
This method corresponds to the play method of the HTMLMediaElement interface in HTML5.
The method completes asynchronously. When the operation starts, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Pauses playback.
If this method succeeds, it returns
This method corresponds to the pause method of the HTMLMediaElement interface in HTML5.
The method completes asynchronously. When the transition to paused is complete, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the audio is muted.
Returns TRUE if the audio is muted, or
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Mutes or unmutes the audio.
Specify TRUE to mute the audio, or
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the audio volume level.
Returns the volume level. Volume is expressed as an attenuation level, where 0.0 indicates silence and 1.0 indicates full volume (no attenuation).
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the audio volume level.
The volume level. Volume is expressed as an attenuation level, where 0.0 indicates silence and 1.0 indicates full volume (no attenuation).
If this method succeeds, it returns
When the audio balance changes, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the current media resource contains a video stream.
Returns TRUE if the current media resource contains a video stream. Returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the current media resource contains an audio stream.
Returns TRUE if the current media resource contains an audio stream. Returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the size of the video frame, adjusted for aspect ratio.
Receives the width in pixels.
Receives the height in pixels.
If this method succeeds, it returns
This method adjusts for the correct picture aspect ratio. For example, if the encoded frame is 720 ? 420 and the picture aspect ratio is 4:3, the method will return a size equal to 640 ? 480 pixels.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the picture aspect ratio of the video stream.
Receives the x component of the aspect ratio.
Receives the y component of the aspect ratio.
If this method succeeds, it returns
The Media Engine automatically converts the pixel aspect ratio to 1:1 (square pixels).
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Shuts down the Media Engine and releases the resources it is using.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Copies the current video frame to a DXGI surface or WIC bitmap.
A reference to the
A reference to an
A reference to a
A reference to an
If this method succeeds, it returns
In frame-server mode, call this method to blit the video frame to a DXGI or WIC surface. The application can call this method at any time after the Media Engine loads a video resource. Typically, however, the application calls
The Media Engine scales and letterboxes the video to fit the destination rectangle. It fills the letterbox area with the border color.
For protected content, call the IMFMediaEngineProtectedContent::TransferVideoFrame method instead of this method.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries the Media Engine to find out whether a new video frame is ready.
If a new frame is ready, receives the presentation time of the frame.
This method can return one of these values.
| Return code | Description |
|---|---|
| The method succeeded, but the Media Engine does not have a new frame. |
| | A new video frame is ready for display. |
?
In frame-server mode, the application should call this method whenever a vertical blank occurs in the display device. If the method returns
Do not call this method in rendering mode or audio-only mode.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries the Media Engine to find out whether a new video frame is ready.
If a new frame is ready, receives the presentation time of the frame.
In frame-server mode, the application should call this method whenever a vertical blank occurs in the display device. If the method returns
Do not call this method in rendering mode or audio-only mode.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the most recent error status.
This method returns the last error status, if any, that resulted from loading the media source. If there has not been an error, ppError receives the value
This method corresponds to the error attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the current error code.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets a list of media sources.
This method corresponds to adding a list of source elements to a media element in HTML5.
The Media Engine tries to load each item in the pSrcElements list, until it finds one that loads successfully. After this method is called, the application can use the
This method completes asynchronously. When the operation starts, the Media Engine sends an
If the Media Engine is unable to load a URL, it sends an
For more information about event handling in the Media Engine, see
If the application also calls
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the URL of a media resource.
This method corresponds to setting the src attribute of the HTMLMediaElement interface in HTML5.
The URL specified by this method takes precedence over media resources specified in the
This method asynchronously loads the URL. When the operation starts, the Media Engine sends an
If the Media Engine is unable to load the URL, the Media Engine sends an
For more information about event handling in the Media Engine, see
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the current network state of the media engine.
This method corresponds to the networkState attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the preload flag.
This method corresponds to the preload attribute of the HTMLMediaElement interface in HTML5. The value is a hint to the user-agent whether to preload the media resource.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries how much resource data the media engine has buffered.
This method corresponds to the buffered attribute of the HTMLMediaElement interface in HTML5.
The returned
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the ready state, which indicates whether the current media resource can be rendered.
This method corresponds to the readyState attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the Media Engine is currently seeking to a new playback position.
This method corresponds to the seeking attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the current playback position.
This method corresponds to the currentTime attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the initial playback position.
This method corresponds to the initialTime attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the duration of the media resource.
This method corresponds to the duration attribute of the HTMLMediaElement interface in HTML5.
If the duration changes, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether playback is currently paused.
This method corresponds to the paused attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the default playback rate.
This method corresponds to getting the defaultPlaybackRate attribute of the HTMLMediaElement interface in HTML5.
The default playback rate is used for the next call to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the current playback rate.
This method corresponds to getting the playbackRate attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the time ranges that have been rendered.
This method corresponds to the played attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the time ranges to which the Media Engine can currently seek.
This method corresponds to the seekable attribute of the HTMLMediaElement interface in HTML5.
To find out whether the media source supports seeking, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether playback has ended.
This method corresponds to the ended attribute of the HTMLMediaElement interface in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the Media Engine automatically begins playback.
This method corresponds to the autoplay attribute of the HTMLMediaElement interface in HTML5.
If this method returns TRUE, playback begins automatically after the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the Media Engine will loop playback.
This method corresponds to getting the loop attribute of the HTMLMediaElement interface in HTML5.
If looping is enabled, the Media Engine seeks to the start of the content when playback reaches the end.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the audio is muted.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the audio volume level.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Notifies the application when a playback event occurs.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Notifies the application when a playback event occurs.
A member of the
The first event parameter. The meaning of this parameter depends on the event code.
The second event parameter. The meaning of this parameter depends on the event code.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Opens a media resource from a byte stream.
A reference to the
The URL of the byte stream.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Opens a media resource from a byte stream.
A reference to the
The URL of the byte stream.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a playback statistic from the Media Engine.
A member of the
A reference to a
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Updates the source rectangle, destination rectangle, and border color for the video.
A reference to an
A reference to a
A reference to an
If this method succeeds, it returns
In rendering mode, call this method to reposition the video, update the border color, or repaint the video frame. If all of the parameters are
In frame-server mode, this method has no effect.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the audio balance.
Returns the balance. The value can be any number in the following range (inclusive).
| Return value | Description |
|---|---|
| The left channel is at full volume; the right channel is silent. |
| The right channel is at full volume; the left channel is silent. |
?
If the value is zero, the left and right channels are at equal volumes. The default value is zero.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the audio balance.
The audio balance. The value can be any number in the following range (inclusive).
| Value | Meaning |
|---|---|
| The left channel is at full volume; the right channel is silent. |
| The right channel is at full volume; the left channel is silent. |
?
If the value is zero, the left and right channels are at equal volumes. The default value is zero.
If this method succeeds, it returns
When the audio balance changes, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the Media Engine can play at a specified playback rate.
The requested playback rate.
Returns TRUE if the playback rate is supported, or
Playback rates are expressed as a ratio of the current rate to the normal rate. For example, 1.0 is normal playback speed, 0.5 is half speed, and 2.0 is 2? speed. Positive values mean forward playback, and negative values mean reverse playback.
The results of this method can vary depending on the media resource that is currently loaded. Some media formats might support faster playback rates than others. Also, some formats might not support reverse play.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Steps forward or backward one frame.
Specify TRUE to step forward or
If this method succeeds, it returns
The frame-step direction is independent of the current playback direction.
This method completes asynchronously. When the operation completes, the Media Engine sends an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets various flags that describe the media resource.
Receives a bitwise OR of zero or more flags. The following flags are defined.
| Value | Meaning |
|---|---|
| The media resource represents a live data source, such as a video camera. If playback is stopped and then restarted, there will be a gap in the content. |
| The media resource supports seeking. To get the seekable range, call |
| The media resource can be paused. |
| Seeking this resource can take a long time. For example, it might download through HTTP. |
?
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a presentation attribute from the media resource.
The attribute to query. For a list of presentation attributes, see Presentation Descriptor Attributes.
A reference to a
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of streams in the media resource.
Receives the number of streams.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets a stream-level attribute from the media resource.
The zero-based index of the stream. To get the number of streams, call
The attribute to query. Possible values are listed in the following topics:
A reference to a
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether a stream is selected to play.
The zero-based index of the stream. To get the number of streams, call
Receives a Boolean value.
| Value | Meaning |
|---|---|
| The stream is selected. During playback, this stream will play. |
| The stream is not selected. During playback, this stream will not play. |
?
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Selects or deselects a stream for playback.
The zero-based index of the stream. To get the number of streams, call
Specifies whether to select or deselect the stream.
| Value | Meaning |
|---|---|
| The stream is selected. During playback, this stream will play. |
| The stream is not selected. During playback, this stream will not play. |
?
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the media resource contains protected content.
Receives the value TRUE if the media resource contains protected content, or
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Inserts a video effect.
One of the following:
Specifies whether the effect is optional.
| Value | Meaning |
|---|---|
| The effect is optional. If the Media Engine cannot add the effect, it ignores the effect and continues playback. |
| The effect is required. If the Media Engine object cannot add the effect, a playback error occurs. |
?
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| The maximum number of video effects was reached. |
?
The effect is applied when the next media resource is loaded.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Inserts an audio effect.
One of the following:
Specifies whether the effect is optional.
| Value | Meaning |
|---|---|
| The effect is optional. If the Media Engine cannot add the effect, it ignores the effect and continues playback. |
| The effect is required. If the Media Engine object cannot add the effect, a playback error occurs. |
?
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| The maximum number of audio effects was reached. |
?
The effect is applied when the next media resource is loaded.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Removes all audio and effects.
If this method succeeds, it returns
Call this method to remove all of the effects that were added with the IMFMediaEngineEx::InsertEffect method.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies a presentation time when the Media Engine will send a marker event.
The presentation time for the marker event, in seconds.
If this method succeeds, it returns
When playback reaches the time specified by timeToFire, the Media Engine sends an
If the application seeks past the marker point, the Media Engine cancels the marker and does not send the event.
During forward playback, set timeToFire to a value greater than the current playback position. During reverse playback, set timeToFire to a value less than the playback position.
To cancel a marker, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the time of the next timeline marker, if any.
Receives the marker time, in seconds. If no marker is set, this parameter receives the value NaN.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Cancels the next pending timeline marker.
If this method succeeds, it returns
Call this method to cancel the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the media resource contains stereoscopic 3D video.
Returns TRUE if the media resource contains 3D video, or
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
For stereoscopic 3D video, gets the layout of the two views within a video frame.
Receives a member of the
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
For stereoscopic 3D video, sets the layout of the two views within a video frame.
A member of the
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
For stereoscopic 3D video, queries how the Media Engine renders the 3D video content.
Receives a member of the
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
For stereoscopic 3D video, specifies how the Media Engine renders the 3D video content.
A member of the
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Enables or disables windowless swap-chain mode.
If TRUE, windowless swap-chain mode is enabled.
If this method succeeds, it returns
In windowless swap-chain mode, the Media Engine creates a windowless swap chain and presents video frames to the swap chain. To render the video, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets a handle to the windowless swap chain.
Receives a handle to the swap chain.
If this method succeeds, it returns
To enable windowless swap-chain mode, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Enables or disables mirroring of the video.
If TRUE, the video is mirrored horizontally. Otherwise, the video is displayed normally.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the audio balance.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets various flags that describe the media resource.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of streams in the media resource.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the media resource contains protected content.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the time of the next timeline marker, if any.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether the media resource contains stereoscopic 3D video.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
For stereoscopic 3D video, gets the layout of the two views within a video frame.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
For stereoscopic 3D video, queries how the Media Engine renders the 3D video content.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets a handle to the windowless swap chain.
To enable windowless swap-chain mode, call
Applies to: desktop apps only
Defines flags for serializing and deserializing attribute stores.
If this flag is set,
Applies to: desktop apps | Metro style apps
Specifies how to compare the attributes on two objects.
Check whether all the attributes in pThis exist in pTheirs and have the same data, where pThis is the object whose Compare method is being called and pTheirs is the object given in the pTheirs parameter.
Check whether all the attributes in pTheirs exist in pThis and have the same data, where pThis is the object whose Compare method is being called and pTheirs is the object given in the pTheirs parameter.
Check whether both objects have identical attributes with the same data.
Check whether the attributes that exist in both objects have the same data.
Find the object with the fewest number of attributes, and check if those attributes exist in the other object and have the same data.
Applies to: desktop apps | Metro style apps
Defines the data type for a key/value pair.
Unsigned 32-bit integer.
Unsigned 64-bit integer.
Floating-point number.
Byte array.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps | Metro style apps
Specifies the origin for a seek request.
The seek position is specified relative to the start of the stream.
The seek position is specified relative to the current read/write position in the stream.
Media Foundation transforms (MFTs) are an evolution of the transform model first introduced with DirectX Media Objects (DMOs). This topic summarizes the main ways in which MFTs differ from DMOs. Read this topic if you are already familiar with the DMO interfaces, or if you want to convert an existing DMO into an MFT.
This topic contains the following sections:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries how likely it is that the Media Engine can play a specified type of media resource.
This method corresponds to the canPlayType attribute of the HTMLMediaElement interface in HTML5.
The canPlayType attribute defines the following values.
| Value | Description |
|---|---|
| "" (empty string) | The user-agent cannot play the resource, or the resource type is "application/octet-stream". |
| "probably" | The user-agent probably can play the resource. |
| "maybe" | Neither of the previous values applies. |
?
The value "probably" is used because a MIME type for a media resource is generally not a complete description of the resource. For example, "video/mp4" specifies an MP4 file with video, but does not describe the codec. Even with the optional codecs parameter, the MIME type omits some information, such as the actual coded bit rate. Therefore, it is usually impossible to be certain that playback is possible until the actual media resource is opened.
A string that contains a MIME type with an optional codecs parameter, as defined in RFC 4281.
Receives an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Contains flags for the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Defines error status codes for the Media Engine.
The values greater than zero correspond to error codes defined for the MediaError object in HTML5.
No error.
The process of fetching the media resource was stopped at the user's request.
A network error occurred while fetching the media resource.
An error occurred while decoding the media resource.
The media resource is not supported.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Defines event codes for the Media Engine.
The application receives Media Engine events through the
Values below 1000 correspond to events defined in HTML 5 for media elements.
The Media Engine has started to load the source. See
The Media Engine is loading the source.
The Media Engine has suspended a load operation.
The Media Engine cancelled a load operation that was in progress.
An error occurred.
| Event Parameter | Description |
|---|---|
| param1 | A member of the |
| param2 | An |
?
The Media Engine has switched to the
The Load algorithm is stalled, waiting for data.
The Media Engine is switching to the playing state. See
The media engine has paused. See
The Media Engine has loaded enough source data to determine the duration and dimensions of the source.
The Media Engine has loaded enough data to render some content (for example, a video frame).
Playback has stopped because the next frame is not available.
Playback has started. See
Playback can start, but the Media Engine might need to stop to buffer more data.
The Media Engine can probably play through to the end of the resource, without stopping to buffer data.
The Media Engine has started seeking to a new playback position. See
The Media Engine has seeked to a new playback position. See
The playback position has changed. See
Playback has reached the end of the source. This event is not sent if the GetLoopis TRUE.
The playback rate has changed. See
The duration of the media source has changed. See
The audio volume changed. See
The output format of the media source has changed.
| Event Parameter | Description |
|---|---|
| param1 | Zero if the video format changed, 1 if the audio format changed. |
| param2 | Zero. |
?
The Media Engine flushed any pending events from its queue.
The playback position reached a timeline marker. See
The audio balance changed. See
The Media Engine has finished downloading the source data.
The media source has started to buffer data.
The media source has stopped buffering data.
The
The Media Engine's Load algorithm is waiting to start.
| Event Parameter | Description |
|---|---|
| param1 | A handle to a waitable event, of type HANDLE. |
| param2 | Zero. |
?
If Media Engine is created with the
If the Media Engine is not created with the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the current network state of the media engine.
This method corresponds to the networkState attribute of the HTMLMediaElement interface in HTML5.
Applies to: desktop apps only
Describes the conversion matrices between Y'PbPr (component video) and studio R'G'B'. These flags are used in the DXVA2_ExtendedFormat structure.
The transfer matrices are defined as follows.
BT.709 transfer matrices:
Y' 0.212600 0.715200 0.072200 R'
Pb = -0.114572 -0.385428 0.500000 x G'
Pr 0.500000 -0.454153 -0.045847 B' R' 1.000000 0.000000 1.574800 Y'
G' = 1.000000 -0.187324 -0.468124 x Pb
B' 1.000000 1.855600 0.000000 Pr
BT.601 transfer matrices:
Y' 0.299000 0.587000 0.114000 R'
Pb = -0.168736 -0.331264 0.500000 x G'
Pr 0.500000 -0.418688 -0.081312 B' R' 1.000000 0.000000 1.402000 Y'
G' = 1.000000 -0.344136 -0.714136 x Pb
B' 1.000000 1.772000 0.000000 Pr
SMPTE 240M (SMPTE RP 145) transfer matrices:
Y' 0.212000 0.701000 0.087000 R'
Pb = -0.116000 -0.384000 0.500000 x G'
Pr 0.500000 -0.445000 -0.055000 B' R' 1.000000 -0.000000 1.576000 Y'
G' = 1.000000 -0.227000 -0.477000 x Pb
B' 1.000000 1.826000 0.000000 Pr
This enumeration is equivalent to the DXVA_VideoTransferMatrix enumeration used in DXVA 1.0.
If you are using the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Contains flags that specify whether the Media Engine will play protected content, and whether the Media Engine will use the Protected Media Path (PMP).
These flags are used with the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Defines ready-state values for the Media Engine.
These values correspond to constants defined for the HTMLMediaElement.readyState attribute in HTML5.
No data is available.
Some metadata is available, including the duration and, for video files, the video dimensions. No media data is available.
There is media data for the current playback position, but not enough data for playback or seeking.
There is enough media data to enable some playback or seeking. The amount of data might be a little as the next video frame.
There is enough data to play the resource, based on the current rate at which the resource is being fetched.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Specifies the layout for a packed 3D video frame.
None.
The views are packed side-by-side in a single frame.
The views are packed top-to-bottom in a single frame.
Applies to: desktop apps only
Describes the conversion matrices between Y'PbPr (component video) and studio R'G'B'. These flags are used in the DXVA2_ExtendedFormat structure.
The transfer matrices are defined as follows.
BT.709 transfer matrices:
Y' 0.212600 0.715200 0.072200 R'
Pb = -0.114572 -0.385428 0.500000 x G'
Pr 0.500000 -0.454153 -0.045847 B' R' 1.000000 0.000000 1.574800 Y'
G' = 1.000000 -0.187324 -0.468124 x Pb
B' 1.000000 1.855600 0.000000 Pr
BT.601 transfer matrices:
Y' 0.299000 0.587000 0.114000 R'
Pb = -0.168736 -0.331264 0.500000 x G'
Pr 0.500000 -0.418688 -0.081312 B' R' 1.000000 0.000000 1.402000 Y'
G' = 1.000000 -0.344136 -0.714136 x Pb
B' 1.000000 1.772000 0.000000 Pr
SMPTE 240M (SMPTE RP 145) transfer matrices:
Y' 0.212000 0.701000 0.087000 R'
Pb = -0.116000 -0.384000 0.500000 x G'
Pr 0.500000 -0.445000 -0.055000 B' R' 1.000000 -0.000000 1.576000 Y'
G' = 1.000000 -0.227000 -0.477000 x Pb
B' 1.000000 1.826000 0.000000 Pr
This enumeration is equivalent to the DXVA_VideoTransferMatrix enumeration used in DXVA 1.0.
If you are using the
Applies to: desktop apps only
Defines messages for an enhanced video renderer (EVR) presenter. This enumeration is used with the IMFVideoPresenter::ProcessMessage method.
Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.
if (Buffer.dwStatus ==
Applies to: desktop apps | Metro style apps
Describes the current status of a call to the IMFShutdown::Shutdown method.
Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.
if (Buffer.dwStatus ==
Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.
if (Buffer.dwStatus ==
Applies to: desktop apps only
Indicates whether a Media Foundation transform (MFT) can produce output data.
There is a sample available for at least one output stream. To retrieve the available output samples, call
Applies to: desktop apps only
Describes an output stream on a Media Foundation transform (MFT).
Before the client sets the media types on the MFT, the only flag guaranteed to be accurate is the
The
MFT_OUTPUT_STREAM_DISCARDABLE: The MFT discards output data only if the client calls ProcessOutput with the
MFT_OUTPUT_STREAM_LAZY_READ: If the client continues to call ProcessInput without collecting the output from this stream, the MFT eventually discards the output. If all output streams have the
If neither of these flags is set, the MFT never discards output data.
Each media sample (
For uncompressed audio formats, this flag is always implied. (It is valid to set the flag, but not required.) An uncompressed audio frame should never span more than one media sample.
Each output sample contains exactly one unit of data, as defined for the
If this flag is present, the
An MFT that outputs uncompressed audio should not set this flag. For efficiency, it should output more than one audio frame at a time.
All output samples are the same size.
The MFT can discard the output data from this output stream, if requested by the client. To discard the output, set the
This output stream is optional. The client can deselect the stream by not setting a media type or by setting a
The MFT provides the output samples for this stream, either by allocating them internally or by operating directly on the input samples. The MFT cannot use output samples provided by the client for this stream.
If this flag is not set, the MFT must set cbSize to a nonzero value in the
The MFT can either provide output samples for this stream or it can use samples that the client allocates. This flag cannot be combined with the
If the MFT does not set this flag or the
The MFT does not require the client to process the output for this stream. If the client continues to send input data without getting the output from this stream, the MFT simply discards the previous input.
The MFT might remove this output stream during streaming. This flag typically applies to demultiplexers, where the input data contains multiple streams that can start and stop during streaming. For more information, see
Applies to: desktop apps only
Defines flags for the
The values in this enumeration are not bit flags, so they should not be combined with a bitwise OR. Also, the caller should test for these flags with the equality operator, not a bitwise AND:
// Correct.
if (Buffer.dwStatus ==
Applies to: desktop apps only
Indicates the status of a call to
If the MFT sets this flag, the ProcessOutput method returns MF_E_TRANSFORM_STREAM_CHANGE and no output data is produced. The client should respond as follows:
Call
Call
Call
Until these steps are completed, all further calls to ProcessOutput return MF_E_TRANSFORM_STREAM_CHANGE.
Applies to: desktop apps only
Defines flags for the setting or testing the media type on a Media Foundation transform (MFT).
Test the proposed media type, but do not set it.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps | Metro style apps
Defines the object types that are created by the source resolver.
Media source. You can query the object for the IMFMediaSource interface.
Byte stream. You can query the object for the
Invalid type.
Applies to: desktop apps | Metro style apps
Sends a message to the Media Foundation transform (MFT).
Before calling this method, set the media types on all input and output streams.
The MFT might ignore certain message types. If so, the method returns
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessMessage. See Creating Hybrid DMO/MFT Objects.
The message to send, specified as a member of the
Message parameter. The meaning of this parameter depends on the message type.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
The video processor MFT is a Microsoft Media Foundation transform (MFT) that performs colorspace conversion, video resizing, deinterlacing, frame rate conversion, rotation, cropping, spatial left and right view unpacking, and mirroring.
An instance of the video processor can be created in one of the following ways:
The video processor supports GPU-accelerated video processing, using Microsoft Direct3D?11. For more information, see
The video processor supports the view unpacking operation on 3D video frames:
If the input frame contains two views packed in the same frame, the video processor can split the views into separate buffers, or extract the base view and discard the second view. To enable view unpacking, set the
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Contains flags that define the chroma encoding scheme for Y'Cb'Cr' data.
These flags are used with the
For more information about these values, see the remarks for the DXVA2_VideoChromaSubSampling enumeration, which is the DirectX Video Acceleration (DXVA) equivalent of this enumeration.
Unknown encoding scheme.
Chroma should be reconstructed as if the underlying video was progressive content, rather than skipping fields or applying chroma filtering to minimize artifacts from reconstructing 4:2:0 interlaced chroma.
Chroma samples are aligned horizontally with the luma samples, or with multiples of the luma samples. If this flag is not set, chroma samples are located 1/2 pixel to the right of the corresponding luma sample.
Chroma samples are aligned vertically with the luma samples, or with multiples of the luma samples. If this flag is not set, chroma samples are located 1/2 pixel down from the corresponding luma sample.
The U and V planes are aligned vertically. If this flag is not set, the chroma planes are assumed to be out of phase by 1/2 chroma sample, alternating between a line of U followed by a line of V.
Specifies the chroma encoding scheme for MPEG-2 video. Chroma samples are aligned horizontally with the luma samples, but are not aligned vertically. The U and V planes are aligned vertically.
Specifies the chroma encoding scheme for MPEG-1 video.
Specifies the chroma encoding scheme for PAL DV video.
Chroma samples are aligned vertically and horizontally with the luma samples. YUV formats such as 4:4:4, 4:2:2, and 4:1:1 are always cosited in both directions and should use this flag.
Reserved.
Reserved. This member forces the enumeration type to compile as a DWORD value.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how a video stream is interlaced.
In the descriptions that follow, upper field refers to the field that contains the leading half scan line. Lower field refers to the field that contains the first full scan line.
Scan lines in the lower field are 0.5 scan line lower than those in the upper field. In NTSC television, a frame consists of a lower field followed by an upper field. In PAL television, a frame consists of an upper field followed by a lower field.
The upper field is also called the even field, the top field, or field 2. The lower field is also called the odd field, the bottom field, or field 1.
If the interlace mode is
The type of interlacing is not known.
Progressive frames.
Interlaced frames. Each frame contains two fields. The field lines are interleaved, with the upper field appearing on the first line.
Interlaced frames. Each frame contains two fields. The field lines are interleaved, with the lower field appearing on the first line.
Interlaced frames. Each frame contains one field, with the upper field appearing first.
Interlaced frames. Each frame contains one field, with the lower field appearing first.
The stream contains a mix of interlaced and progressive modes.
Reserved.
Reserved. This member forces the enumeration type to compile as a DWORD value.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps only
Specifies how the credential manager should obtain user credentials.
The application implements the credential manager, which must expose the IMFNetCredentialManager interface. If the REQUIRE_PROMPT flag is set, the credential manager should prompt the user for his or her name and password.
The credential cache object sets the REQUIRE_PROMPT flag if the cache does not yet contain valid credentials. It also sets this flag if the credentials will be sent as plain text, unless the credential manager previously set the MFNET_CREDENTIAL_ALLOW_CLEAR_TEXT option. (See IMFNetCredentialCache::SetUserOptions.)
The credential manager should prompt the user to provide the credentials.
Note??Requires Windows?7 or later.
The credentials are saved to persistent storage. This flag acts as a hint for the application's UI. If the application prompts the user for credentials, the UI can indicate that the credentials have already been saved.
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
Version number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Version parameter requires a newer version of Media Foundation than the version that is running. |
| The Media Foundation platform is disabled because the system was started in "Safe Mode" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates a media buffer that wraps an existing media buffer. The new media buffer points to the same memory as the original media buffer, or to an offset from the start of the memory.
A reference to the
The start of the new buffer, as an offset in bytes from the start of the original buffer.
The size of the new buffer. The value of cbOffset + dwLength must be less than or equal to the size of valid data the original buffer. (The size of the valid data is returned by the
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| The requested offset or the requested length is not valid. |
?
The maximum size of the wrapper buffer is limited to the size of the valid data in the original buffer. This might be less than the allocated size of the original buffer. To set the size of the valid data, call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the size of the buffer needed for the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Use this function to find the size of the array that is needed for the
Applies to: desktop apps | Metro style apps
Unlocks the Media Foundation platform after it was locked by a call to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
The application must call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an empty media sample.
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Initially the sample does not contain any media buffers.
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an empty attribute store.
Receives a reference to the
The initial number of elements allocated for the attribute store. The attribute store grows as needed.
If this function succeeds, it returns
Attributes are used throughout Microsoft Media Foundation to configure objects, describe media formats, query object properties, and other purposes. For more information, see Attributes in Media Foundation.
For a complete list of all the defined attribute GUIDs in Media Foundation, see Media Foundation Attributes.
Applies to: desktop apps | Metro style apps
Creates an asynchronous result object. Use this function if you are implementing an asynchronous method.
Pointer to the object stored in the asynchronous result. This reference is returned by the
Pointer to the
Pointer to the
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
To invoke the callback specified in pCallback, call the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an object that allocates video samples that are compatible with Microsoft DirectX Graphics Infrastructure (DXGI).
The identifier of the interface to retrieve. Specify one of the following values.
| Value | Meaning |
|---|---|
| Retrieve an |
| Retrieve an IMFVideoSampleAllocator reference. |
| Retrieve an IMFVideoSampleAllocatorEx reference. |
| Retrieve an IMFVideoSampleAllocatorCallback reference. |
?
Receives a reference to the requested interface. The caller must release the interface.
If this function succeeds, it returns
This function creates an allocator for DXGI video surfaces. The buffers created by this allocator expose the
Applies to: desktop apps | Metro style apps
Invokes a callback method to complete an asynchronous operation.
Pointer to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| Invalid work queue. For more information, see |
| The |
?
If you are implementing an asynchronous method, use this function to invoke the caller's
The callback is invoked from a Media Foundation work queue. For more information, see Writing an Asynchronous Method.
The
Applies to: desktop apps | Metro style apps
Shuts down the Microsoft Media Foundation platform. Call this function once for every call to
If this function succeeds, it returns
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the size of the buffer needed for the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
Use this function to find the size of the array that is needed for the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unlocks the shared Microsoft DirectX Graphics Infrastructure (DXGI) Device Manager.
If this function succeeds, it returns
Call this function after a successful call to the
Applies to: desktop apps | Metro style apps
Allocates system memory with a specified byte alignment and creates a media buffer to manage the memory.
Size of the buffer, in bytes.
Specifies the memory alignment for the buffer. Use one of the following constants.
| Value | Meaning |
|---|---|
| Align to 1 bytes. |
| Align to 2 bytes. |
| Align to 4 bytes. |
| Align to 8 bytes. |
| Align to 16 bytes. |
| Align to 32 bytes. |
| Align to 64 bytes. |
| Align to 128 bytes. |
| Align to 256 bytes. |
| Align to 512 bytes. |
?
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
When the media buffer object is destroyed, it releases the allocated memory.
Applies to: desktop apps only
Creates an empty collection object.
Receives a reference to the collection object's
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates an instance of the Microsoft DirectX Graphics Infrastructure (DXGI) Device Manager.
Receives a token that identifies this instance of the DXGI Device Manager. Use this token when calling
Receives a reference to the
If this function succeeds, it returns
Applies to: desktop apps | Metro style apps
Blocks the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
?
This function prevents work queue threads from being shut down when
This function holds a lock on the Media Foundation platform. To unlock the platform, call
The
The default implementation of the
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Allocates system memory and creates a media buffer to manage it.
Size of the buffer, in bytes.
Receives a reference to the
The function returns an
| Return code | Description |
|---|---|
| | The function succeeded. |
| Insufficient memory. |
?
The function allocates a buffer with a 1-byte memory alignment. To allocate a buffer that is aligned to a larger memory boundary, call
When the media buffer object is destroyed, it releases the allocated memory.
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
Version number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Version parameter requires a newer version of Media Foundation than the version that is running. |
| The Media Foundation platform is disabled because the system was started in "Safe Mode" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a system-memory buffer object to hold 2D image data.
Width of the image, in pixels.
Height of the image, in pixels.
A FOURCC code or D3DFORMAT value that specifies the video format. If you have a video subtype
If TRUE, the buffer's
For more information about top-down versus bottom-up images, see Image Stride.
Receives a reference to the
This function can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| Unrecognized video format. |
?
The returned buffer object also exposes the
Applies to: desktop apps | Metro style apps
Calculates ((a * b) + d) / c, where each term is a 64-bit signed value.
A multiplier.
Another multiplier.
The divisor.
The rounding factor.
Returns the result of the calculation. If numeric overflow occurs, the function returns _I64_MAX (positive overflow) or LLONG_MIN (negative overflow). If Mfplat.dll cannot be loaded, the function returns _I64_MAX.
Note??A previous version of this topic described the parameters incorrectly. The divisor is c and the rounding factor is d.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a media buffer to manage a Microsoft DirectX Graphics Infrastructure (DXGI) surface.
Identifies the type of DXGI surface. This value must be IID_ID3D11Texture2D.
A reference to the
The zero-based index of a subresource of the surface. The media buffer object is associated with this subresource.
If TRUE, the buffer's
For more information about top-down versus bottom-up images, see Image Stride.
Receives a reference to the
If this function succeeds, it returns
The returned buffer object supports the following interfaces:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Unlocks the shared Microsoft DirectX Graphics Infrastructure (DXGI) Device Manager.
If this function succeeds, it returns
Call this function after a successful call to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Creates a Microsoft Media Foundation byte stream that wraps an IRandomAccessStream object.
If this function succeeds, it returns
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
Version number. Use the value
This parameter is optional when using C++ but required in C. The value must be one of the following flags:
| Value | Meaning |
|---|---|
| Do not initialize the sockets library. |
| Equivalent to MFSTARTUP_NOSOCKET. |
| Initialize the entire Media Foundation platform. This is the default value when dwFlags is not specified. |
?
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Version parameter requires a newer version of Media Foundation than the version that is running. |
| The Media Foundation platform is disabled because the system was started in "Safe Mode" (fail-safe boot). |
?
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Loads attributes from a stream into an attribute store.
Pointer to the
Bitwise OR of zero or more flags from the
Pointer to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Use this function to deserialize an attribute store that was serialized with the
If dwOptions contains the
If the
Otherwise, the function calls CoUnmarshalInterface to deserialize a proxy for the object.
This function deletes any attributes that were previously stored in pAttr.
Applies to: desktop apps | Metro style apps
Loads attributes from a stream into an attribute store.
Pointer to the
Bitwise OR of zero or more flags from the
Pointer to the
The function returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Use this function to deserialize an attribute store that was serialized with the
If dwOptions contains the
If the
Otherwise, the function calls CoUnmarshalInterface to deserialize a proxy for the object.
This function deletes any attributes that were previously stored in pAttr.
Applies to: desktop apps | Metro style apps
Creates the object associated with this activation object.
Some Microsoft Media Foundation objects must be shut down before being released. If so, the caller is responsible for shutting down the object that is returned in ppv. To shut down the object, do one of the following:
The
After the first call to ActivateObject, subsequent calls return a reference to the same instance, until the client calls either ShutdownObject or
Applies to: desktop apps | Metro style apps
Provides a generic way to store key/value pairs on an object. The keys are
For a list of predefined attribute
To create an empty attribute store, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Compares the attributes on this object with the attributes on another object.
Pointer to the
Member of the
Receives a Boolean value. The value is TRUE if the two sets of attributes match in the way specified by the MatchType parameter. Otherwise, the value is
If pThis is the object whose Compare method is called, and pTheirs is the object passed in as the pTheirs parameter, the following comparisons are defined by MatchType.
| Match type | Returns TRUE if and only if |
|---|---|
| For every attribute in pThis, an attribute with the same key and value exists in pTheirs. | |
| For every attribute in pTheirs, an attribute with the same key and value exists in pThis. | |
| The key/value pairs are identical in both objects. | |
| Take the intersection of the keys in pThis and the keys in pTheirs. The values associated with those keys are identical in both pThis and pTheirs. | |
| Take the object with the smallest number of attributes. For every attribute in that object, an attribute with the same key and value exists in the other object. |
?
The pTheirs and pbResult parameters must not be
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a UINT32 value associated with a key.
Receives a UINT32 value. If the key is found and the data type is UINT32, the method copies the value into this parameter. Otherwise, the original value of this parameter is not changed.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a UINT64 value associated with a key.
Receives a UINT64 value. If the key is found and the data type is UINT64, the method copies the value into this parameter. Otherwise, the original value of this parameter is not changed.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a double value associated with a key.
Receives a double value. If the key is found and the data type is double, the method copies the value into this parameter. Otherwise, the original value of this parameter is not changed.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a
Receives a
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of a string value associated with a key.
If the key is found and the value is a string type, this parameter receives the number of characters in the string, not including the terminating
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a wide-character string associated with a key.
Pointer to a wide-character array allocated by the caller. The array must be large enough to hold the string, including the terminating
The size of the pwszValue array, in characters. This value includes the terminating
Receives the number of characters in the string, excluding the terminating
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The length of the string is too large to fit in a UINT32 value. |
| The buffer is not large enough to hold the string. |
| The specified key was not found. |
| The attribute value is not a string. |
?
You can also use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets a wide-character string associated with a key. This method allocates the memory for the string.
A
If the key is found and the value is a string type, this parameter receives a copy of the string. The caller must free the memory for the string by calling CoTaskMemFree.
Receives the number of characters in the string, excluding the terminating
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The specified key was not found. |
| The attribute value is not a string. |
?
To copy a string value into a caller-allocated buffer, use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Note??An earlier version of the documentation incorrectly stated that the pcchLength parameter can be
Applies to: desktop apps | Metro style apps
Retrieves the length of a byte array associated with a key.
If the key is found and the value is a byte array, this parameter receives the size of the array, in bytes.
To get the byte array, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a byte array associated with a key. This method copies the array into a caller-allocated buffer.
Pointer to a buffer allocated by the caller. If the key is found and the value is a byte array, the method copies the array into this buffer. To find the required size of the buffer, call
The size of the pBuf buffer, in bytes.
Receives the size of the byte array. This parameter can be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The buffer is not large enough to the array. |
| The specified key was not found. |
| The attribute value is not a byte array. |
?
You can also use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves a byte array associated with a key. This method allocates the memory for the array.
If the key is found and the value is a byte array, this parameter receives a copy of the array. The caller must free the memory for the array by calling CoTaskMemFree.
Receives the size of the array, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The specified key was not found. |
| The attribute value is not a byte array. |
?
To copy a byte array value into a caller-allocated buffer, use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an interface reference associated with a key.
Interface identifier (IID) of the interface to retrieve.
Receives a reference to the requested interface. The caller must release the interface.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The attribute value is an |
| The specified key was not found. |
| The attribute value is not an |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds an attribute value with a specified key.
A
A
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
| Invalid attribute type. |
?
This method checks whether the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Removes a key/value pair from the object's attribute list.
guidKey
[in]
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
If the specified key does not exist, the method returns
Client: Requires Windows Vista.
Header: Defined in mfobjects.h; include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFAttributes InterfaceApplies to: desktop apps | Metro style apps
Removes all key/value pairs from the object's attribute list.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a UINT32 value with a key.
New value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the UINT32 value, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a UINT64 value with a key.
New value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the UINT64 value, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a double value with a key.
New value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the double value, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a
New value for this key.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
?
To retrieve the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Associates a wide-character string with a key.
Null-terminated wide-character string to associate with this key. The method stores a copy of the string.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To retrieve the string, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Associates a byte array with a key.
guidKey
[in]
pBuf
[in] Pointer to a byte array to associate with this key. The method stores a copy of the array.
cbBufSize
[in] Size of the array, in bytes.
The method returns an
| Return code | Description |
|---|---|
| E_OUTOFMEMORY | Insufficient memory. |
| | The method succeeded. |
Client: Requires Windows Vista.
Header: Defined in mfobjects.h; include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFAttributes InterfaceApplies to: desktop apps | Metro style apps
Locks the attribute store so that no other thread can access it. If the attribute store is already locked by another thread, this method blocks until the other thread unlocks the object. After calling this method, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method can cause a deadlock if a thread that calls LockStore waits on a thread that calls any other
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Unlocks the attribute store after a call to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of attributes that are set on this object.
Receives the number of attributes. This parameter must not be
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To enumerate all of the attributes, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an attribute at the specified index.
Index of the attribute to retrieve. To get the number of attributes, call
Receives the
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid index. |
?
To enumerate all of an object's attributes in a thread-safe way, do the following:
Call
Call
Call GetItemByIndex to get each attribute by index.
Call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Copies all of the attributes from this object into another attribute store.
A reference to the
If this method succeeds, it returns
This method deletes all of the attributes originally stored in pDest.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Attributes are used throughout Microsoft Media Foundation to configure objects, describe media formats, query object properties, and other purposes. For more information, see Attributes in Media Foundation.
For a complete list of all the defined attribute GUIDs in Media Foundation, see Media Foundation Attributes.
Applies to: desktop apps | Metro style apps
Retrieves an attribute at the specified index.
Index of the attribute to retrieve. To get the number of attributes, call
Receives the
To enumerate all of an object's attributes in a thread-safe way, do the following:
Call
Call
Call GetItemByIndex to get each attribute by index.
Call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds an attribute value with a specified key.
A
A
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
| Invalid attribute type. |
?
This method checks whether the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds an attribute value with a specified key.
A
A
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Insufficient memory. |
| Invalid attribute type. |
?
This method checks whether the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of attributes that are set on this object.
To enumerate all of the attributes, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates the object associated with this activation object.
Interface identifier (IID) of the requested interface.
Receives a reference to the requested interface. The caller must release the interface.
If this method succeeds, it returns
Some Microsoft Media Foundation objects must be shut down before being released. If so, the caller is responsible for shutting down the object that is returned in ppv. To shut down the object, do one of the following:
The
After the first call to ActivateObject, subsequent calls return a reference to the same instance, until the client calls either ShutdownObject or
Applies to: desktop apps | Metro style apps
Shuts down the created object.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If you create an object by calling
The component that calls ActivateObject?not the component that creates the activation object?is responsible for calling ShutdownObject. For example, in a typical playback application, the application creates activation objects for the media sinks, but the Media Session calls ActivateObject. Therefore the Media Session, not the application, calls ShutdownObject.
After ShutdownObject is called, the activation object releases all of its internal references to the created object. If you call ActivateObject again, the activation object will create a new instance of the other object.
Applies to: desktop apps | Metro style apps
Detaches the created object from the activation object.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
?
The activation object releases all of its internal references to the created object. If you call ActivateObject again, the activation object will create a new instance of the other object.
The DetachObject method does not shut down the created object. If the DetachObject method succeeds, the client must shut down the created object. This rule applies only to objects that have a shutdown method or that support the IMFShutdown interface. See the remarks for
Implementation of this method is optional. If the activation object does not support this method, the method returns E_NOTIMPL.
Applies to: desktop apps | Metro style apps
Callback interface to notify the application when an asynchronous method completes.
For more information about asynchronous methods in Microsoft Media Foundation, see Asynchronous Callback Methods.
This interface is also used to perform a work item in a Media Foundation work-queue. For more information, see Work Queues.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Provides configuration information to the dispatching thread for a callback.
Receives a flag indicating the behavior of the callback object's
| Value | Meaning |
|---|---|
| The callback does not take a long time to complete, but has no specific restrictions on what system calls it makes. The callback generally takes less than 30 milliseconds to complete. |
| The callback does very minimal processing. It takes less than 1 millisecond to complete. The callback must be invoked from one of the following work queues:
|
| Implies MFASYNC_FAST_IO_PROCESSING_CALLBACK, with the additional restriction that the callback does no processing (less than 50 microseconds), and the only system call it makes is SetEvent. The callback must be invoked from one of the following work queues:
|
| Blocking callback. |
| Reply callback. |
?
Receives the identifier of the work queue on which the callback is dispatched.
This value can specify one of the standard Media Foundation work queues, or a work queue created by the application. For list of standard Media Foundation work queues, see Work Queue Identifiers. To create a new work queue, call MFAllocateWorkQueue. The default value is MFASYNC_CALLBACK_QUEUE_STANDARD.
If the work queue is not compatible with the value returned in pdwFlags, the Media Foundation platform returns MF_E_INVALID_WORKQUEUE when it tries to dispatch the callback. (See MFPutWorkItem.)
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. Assume the default behavior. |
?
The GetParameters method returns information about the callback so that the dispatching thread can optimize the process that it uses to invoke the callback.
If the method returns a value other than zero in the pdwFlags parameter, your Invoke method must meet the requirements described here. Otherwise, the callback might delay the pipeline.
If you want default values for both parameters, return E_NOTIMPL. The default values are given in the parameter descriptions on this page.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Called when an asynchronous operation is completed.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Within your implementation of Invoke, call the corresponding End... method.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Provides information about the result of an asynchronous operation.
Use this interface to complete an asynchronous operation. You get a reference to this interface when your callback object's
If you are implementing an asynchronous method, call
Any custom implementation of this interface must inherit the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method.
Receives a reference to the state object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There is no state object associated with this asynchronous result. |
?
The caller of the asynchronous method specifies the state object, and can use it for any caller-defined purpose. The state object can be
If you are implementing an asynchronous method, set the state object on the through the punkState parameter of the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the status of the asynchronous operation.
The method returns an
| Return code | Description |
|---|---|
| | The operation completed successfully. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Sets the status of the asynchronous operation.
hrStatus
The status of the asynchronous operation.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
If you implement an asynchronous method, call SetStatus to set the status code for the operation.
Client: Requires Windows Vista.
Header: Defined in mfobjects.h; include mfidl.h.
Library: Use mfuuid.lib.
ReferenceIMFAsyncResult InterfaceConceptsAsynchronous Callback MethodsApplies to: desktop apps | Metro style apps
Returns an object associated with the asynchronous operation. The type of object, if any, depends on the asynchronous method that was called.
Receives a reference to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| There is no object associated with this asynchronous result. |
?
Typically, this object is used by the component that implements the asynchronous method. It provides a way for the function that invokes the callback to pass information to the asynchronous End... method that completes the operation.
If you are implementing an asynchronous method, you can set the object through the punkObject parameter of the
If the asynchronous result object's internal
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method, without incrementing the object's reference count.
Returns a reference to the state object's
This method cannot be called remotely.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method.
The caller of the asynchronous method specifies the state object, and can use it for any caller-defined purpose. The state object can be
If you are implementing an asynchronous method, set the state object on the through the punkState parameter of the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the status of the asynchronous operation.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns an object associated with the asynchronous operation. The type of object, if any, depends on the asynchronous method that was called.
Typically, this object is used by the component that implements the asynchronous method. It provides a way for the function that invokes the callback to pass information to the asynchronous End... method that completes the operation.
If you are implementing an asynchronous method, you can set the object through the punkObject parameter of the
If the asynchronous result object's internal
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Returns the state object specified by the caller in the asynchronous Begin method, without incrementing the object's reference count.
This method cannot be called remotely.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents a buffer that contains a two-dimensional surface, such as a video frame.
To get a reference to this interface, call QueryInterface on the media buffer.
To use a 2-D buffer, it is important to know the stride, which is the number of bytes needed to go from one row of pixels to the next. The stride may be larger than the image width, because the surface may contain padding bytes after each row of pixels. Stride can also be negative, if the pixels are oriented bottom-up in memory. For more information, see Image Stride.
Every video format defines a contiguous or packed representation. This representation is compatible with the standard layout of a DirectX surface in system memory, with no additional padding. For RGB video, the contiguous representation has a pitch equal to the image width in bytes, rounded up to the nearest DWORD boundary. For YUV video, the layout of the contiguous representation depends on the YUV format. For planar YUV formats, the Y plane might have a different pitch than the U and V planes.
If a media buffer supports the
Call the Lock2D method to access the 2-D buffer in its native format. The native format might not be contiguous. The buffer's
For uncompressed images, the amount of valid data in the buffer is determined by the width, height, and pixel layout of the image. For this reason, if you call Lock2D to access the buffer, do not rely on the values returned by
Applies to: desktop apps | Metro style apps
Gives the caller access to the memory in the buffer.
Receives a reference to the first byte of the top row of pixels in the image. The top row is defined as the top row when the image is presented to the viewer, and might not be the first row in memory.
Receives the surface stride, in bytes. The stride might be negative, indicating that the image is oriented from the bottom up in memory.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Cannot lock the Direct3D surface. |
| The buffer cannot be locked at this time. |
?
If p is a reference to the first byte in a row of pixels, p + (*plPitch) points to the first byte in the next row of pixels. A buffer might contain padding after each row of pixels, so the stride might be wider than the width of the image in bytes. Do not access the memory that is reserved for padding bytes, because it might not be read-accessible or write-accessible. For more information, see Image Stride.
The reference returned in pbScanline0 remains valid as long as the caller holds the lock. When you are done accessing the memory, call
The values returned by the
The
When the underlying buffer is a Direct3D surface, the method fails if the surface is not lockable.
Applies to: desktop apps | Metro style apps
Unlocks a buffer that was previously locked. Call this method once for each call to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves a reference to the buffer memory and the surface stride.
Receives a reference to the first byte of the top row of pixels in the image.
Receives the stride, in bytes. For more information, see Image Stride.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| | You must lock the buffer before calling this method. |
?
Before calling this method, you must lock the buffer by calling
Applies to: desktop apps | Metro style apps
Queries whether the buffer is contiguous in its native format.
Receives a Boolean value. The value is TRUE if the buffer is contiguous, and
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Retrieves the number of bytes needed to store the contents of the buffer in contiguous format.
Receives the number of bytes needed to store the contents of the buffer in contiguous format.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Copies this buffer into the caller's buffer, converting the data to contiguous format.
Pointer to the destination buffer where the data will be copied. The caller allocates the buffer.
Size of the destination buffer, in bytes. To get the required size, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid size specified in pbDestBuffer. |
?
If the original buffer is not contiguous, this method converts the contents into contiguous format during the copy. For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Copies data to this buffer from a buffer that has a contiguous format.
Pointer to the source buffer. The caller allocates the buffer.
Size of the source buffer, in bytes. To get the maximum size of the buffer, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This method copies the contents of the source buffer into the buffer that is managed by this
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in the
Applies to: desktop apps | Metro style apps
Queries whether the buffer is contiguous in its native format.
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
Applies to: desktop apps | Metro style apps
Retrieves the number of bytes needed to store the contents of the buffer in contiguous format.
For a definition of contiguous as it applies to 2-D buffers, see the Remarks section in
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gives the caller access to the memory in the buffer.
When you are done accessing the memory, call
This method is equivalent to the
The ppbBufferStart and pcbBufferLength parameters receive the bounds of the buffer memory. Use these values to guard against buffer overruns. Use the values of ppbScanline0 and plPitch to access the image data. If the image is bottom-up in memory, ppbScanline0 will point to the last scan line in memory and plPitch will be negative. For more information, see Image Stride.
The lockFlags parameter specifies whether the buffer is locked for read-only access, write-only access, or read/write access.
When possible, use a read-only or write-only lock, and avoid locking the buffer for read/write access. If the buffer represents a DirectX Graphics Infrastructure (DXGI) surface, a read/write lock can cause an extra copy between CPU memory and GPU memory.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gives the caller access to the memory in the buffer.
A member of the
Receives a reference to the first byte of the top row of pixels in the image. The top row is defined as the top row when the image is presented to the viewer, and might not be the first row in memory.
Receives the surface stride, in bytes. The stride might be negative, indicating that the image is oriented from the bottom up in memory.
Receives a reference to the start of the accessible buffer in memory.
Receives the length of the buffer, in bytes.
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| Invalid request. The buffer might already be locked with an incompatible locking flag. See Remarks. |
?
When you are done accessing the memory, call
This method is equivalent to the
The ppbBufferStart and pcbBufferLength parameters receive the bounds of the buffer memory. Use these values to guard against buffer overruns. Use the values of ppbScanline0 and plPitch to access the image data. If the image is bottom-up in memory, ppbScanline0 will point to the last scan line in memory and plPitch will be negative. For more information, see Image Stride.
The lockFlags parameter specifies whether the buffer is locked for read-only access, write-only access, or read/write access.
When possible, use a read-only or write-only lock, and avoid locking the buffer for read/write access. If the buffer represents a DirectX Graphics Infrastructure (DXGI) surface, a read/write lock can cause an extra copy between CPU memory and GPU memory.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Copies the buffer to another 2D buffer object.
A reference to the
If this method succeeds, it returns
The destination buffer must be at least as large as the source buffer.
Applies to: desktop apps | Metro style apps
Controls how a byte stream buffers data from a network.
To get a reference to this interface, call QueryInterface on the byte stream object.
If a byte stream implements this interface, a media source can use it to control how the byte stream buffers data. This interface is designed for byte streams that read data from a network.
A byte stream that implements this interface should also implement the
The byte stream must send a matching
After the byte stream sends an
The byte stream should not send any more buffering events after it reaches the end of the file.
If buffering is disabled, the byte stream does not send any buffering events. Internally, however, it might still buffer data while it waits for I/O requests to complete. Therefore,
If the byte stream is buffering data internally and the media source calls EnableBuffering with the value TRUE, the byte stream can send
After the presentation has started, the media source should forward and
Applies to: desktop apps | Metro style apps
Sets the buffering parameters.
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Enables or disables buffering.
Specifies whether the byte stream buffers data. If TRUE, buffering is enabled. If
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Before calling this method, call
Applies to: desktop apps | Metro style apps
Stops any buffering that is in progress.
The method returns an
| Return code | Description |
|---|---|
| | The byte stream successfully stopped buffering. |
| No buffering was in progress. |
?
If the byte stream is currently buffering data, it stops and sends an
Applies to: desktop apps | Metro style apps
Sets the buffering parameters.
Applies to: desktop apps only
Stops the background transfer of data to the local cache.
The byte stream resumes transferring data to the cache if the application does one of the following:
Applies to: desktop apps only
Stops the background transfer of data to the local cache.
If this method succeeds, it returns
The byte stream resumes transferring data to the cache if the application does one of the following:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Queries whether background transfer is active.
Background transfer might stop because the cache limit was reached (see
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the ranges of bytes that are currently stored in the cache.
Receives the number of ranges returned in the ppRanges array.
Receives an array of
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Limits the cache size.
The maximum number of bytes to store in the cache, or ULONGLONG_MAX for no limit. The default value is no limit.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Queries whether background transfer is active.
Receives the value TRUE if background transfer is currently active, or
If this method succeeds, it returns
Background transfer might stop because the cache limit was reached (see
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Limits the cache size.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Queries whether background transfer is active.
Background transfer might stop because the cache limit was reached (see
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the result of a time-based seek.
This method returns the server response from a previous time-based seek.
Note??This method normally cannot be invoked until some data is read from the byte stream, because the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Queries whether the byte stream supports time-based seeking.
Receives the value TRUE if the byte stream supports time-based seeking, or
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Seeks to a new position in the byte stream.
The new position, in 100-nanosecond units.
If this method succeeds, it returns
If the byte stream reads from a server, it might cache the seek request until the next read request. Therefore, the byte stream might not send a request to the server immediately.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Gets the result of a time-based seek.
Receives the new position after the seek, in 100-nanosecond units.
Receives the stop time, in 100-nanosecond units. If the stop time is unknown, the value is zero.
Receives the total duration of the file, in 100-nanosecond units. If the duration is unknown, the value is ?1.
This method can return one of these values.
| Return code | Description |
|---|---|
| | The method succeeded. |
| The byte stream does not support time-based seeking, or no data is available. |
?
This method returns the server response from a previous time-based seek.
Note??This method normally cannot be invoked until some data is read from the byte stream, because the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Queries whether the byte stream supports time-based seeking.
Applies to: desktop apps | Metro style apps
Retrieves the number of objects in the collection.
Applies to: desktop apps | Metro style apps
Retrieves the number of objects in the collection.
Receives the number of objects in the collection.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves an object in the collection.
Zero-based index of the object to retrieve. Objects are indexed in the order in which they were added to the collection.
Receives a reference to the object's
If this method succeeds, it returns
This method does not remove the object from the collection. To remove an object, call
Applies to: desktop apps | Metro style apps
Adds an object to the collection.
Pointer to the object's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
If pUnkElement is
Applies to: desktop apps | Metro style apps
Removes an object from the collection.
Zero-based index of the object to remove. Objects are indexed in the order in which they were added to the collection.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Adds an object at the specified index in the collection.
The zero-based index where the object will be added to the collection.
The object to insert.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Removes all items from the collection.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Applies to: desktop apps | Metro style apps
Retrieves the number of objects in the collection.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries the Microsoft DirectX Graphics Infrastructure (DXGI) surface for an interface.
You can use this method to get a reference to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries the Microsoft DirectX Graphics Infrastructure (DXGI) surface for an interface.
The interface identifer (IID) of the interface being requested.
Receives a reference to the interface. The caller must release the interface.
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| The object does not support the specified interface. |
| Invalid request. |
?
You can use this method to get a reference to the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the index of the subresource that is associated with this media buffer.
Receives the zero-based index of the subresource.
If this method succeeds, it returns
The subresource index is specified when you create the media buffer object. See
For more information about texture subresources, see
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets an
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| The object does not support the specified interface. |
| The specified key was not found. |
?
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Stores an arbitrary
This method can return one of these values.
| Return code | Description |
|---|---|
| | Success. |
| | An item already exists with this key. |
?
To retrieve the reference from the object, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the index of the subresource that is associated with this media buffer.
The subresource index is specified when you create the media buffer object. See
For more information about texture subresources, see
Applies to: desktop apps | Metro style apps
Represents a block of memory that contains media data. Use this interface to access the data in the buffer.
If the buffer contains 2-D image data (such as an uncompressed video frame), you should query the buffer for the
To get a buffer from a media sample, call one of the following
To create a new buffer object, use one of the following functions.
| Function | Description |
|---|---|
| | Creates a buffer and allocates system memory. |
| | Creates a media buffer that wraps an existing media buffer. |
| MFCreateDXSurfaceBuffer | Creates a buffer that manages a DirectX surface. |
| | Creates a buffer and allocates system memory with a specified alignment. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gives the caller access to the memory in the buffer, for reading or writing
Receives the maximum amount of data that can be written to the buffer. This parameter can be
Receives the length of the valid data in the buffer, in bytes. This parameter can be
Receives a reference to the start of the buffer.
This method gives the caller access to the entire buffer, up to the maximum size returned in the pcbMaxLength parameter. The value returned in pcbCurrentLength is the size of any valid data already in the buffer, which might be less than the total buffer size.
The reference returned in ppbBuffer is guaranteed to be valid, and can safely be accessed across the entire buffer for as long as the lock is held. When you are done accessing the buffer, call
Locking the buffer does not prevent other threads from calling Lock, so you should not rely on this method to synchronize threads.
This method does not allocate any memory, or transfer ownership of the memory to the caller. Do not release or free the memory; the media buffer will free the memory when the media buffer is destroyed.
If you modify the contents of the buffer, update the current length by calling
If the buffer supports the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Unlocks a buffer that was previously locked. Call this method once for every call to
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| For Direct3D surface buffers, an error occurred when unlocking the surface. |
?
It is an error to call Unlock if you did not call Lock previously.
After calling this method, do not use the reference returned by the Lock method. It is no longer guaranteed to be valid.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the valid data in the buffer.
Receives the length of the valid data, in bytes. If the buffer does not contain any valid data, the value is zero.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the length of the valid data in the buffer.
Length of the valid data, in bytes. This value cannot be greater than the allocated size of the buffer, which is returned by the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The specified length is greater than the maximum size of the buffer. |
?
Call this method if you write data into the buffer.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the allocated size of the buffer.
Receives the allocated size of the buffer, in bytes.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
The buffer might or might not contain any valid data, and if there is valid data in the buffer, it might be smaller than the buffer's allocated size. To get the length of the valid data, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the length of the valid data in the buffer.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the allocated size of the buffer.
The buffer might or might not contain any valid data, and if there is valid data in the buffer, it might be smaller than the buffer's allocated size. To get the length of the valid data, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Provides the Media Engine with a list of media resources.
The
This interface enables the application to provide the same audio/video content in several different encoding formats, such as H.264 and Windows Media Video. If a particular codec is not present on the user's computer, the Media Engine will try the next URL in the list. To use this interface, do the following:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of source elements in the list.
Returns the number of source elements.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the URL of an element in the list.
The zero-based index of the source element. To get the number of source elements, call
Receives a BSTR that contains the URL of the source element. The caller must free the BSTR by calling SysFreeString. If no URL is set, this parameter receives the value
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the MIME type of an element in the list.
The zero-based index of the source element. To get the number of source elements, call
Receives a BSTR that contains the MIME type. The caller must free the BSTR by calling SysFreeString. If no MIME type is set, this parameter receives the value
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the intended media type of an element in the list.
The zero-based index of the source element. To get the number of source elements, call
Receives a BSTR that contains a media-query string. The caller must free the BSTR by calling SysFreeString. If no media type is set, this parameter receives the value
If this method succeeds, it returns
The string returned in pMedia should be a media-query string that conforms to the W3C Media Queries specification.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Adds a source element to the end of the list.
The URL of the source element, or
The MIME type of the source element, or
A media-query string that specifies the intended media type, or
If this method succeeds, it returns
Any of the parameters to this method can be
This method allocates copies of the BSTRs that are passed in.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Removes all of the source elements from the list.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of source elements in the list.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Provides the current error status for the Media Engine.
The
To get a reference to this interface, call
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the error code.
Returns a value from the
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extended error code.
Returns an
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the error code.
The error code, specified as an
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Sets the extended error code.
An
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the extended error code.
Applies to: desktop apps | Metro style apps
Retrieves an
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the event type. The event type indicates what happened to trigger the event. It also defines the meaning of the event value.
Receives the event type. For a list of event types, see Media Foundation Events.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the extended type of the event.
Receives a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
To define a custom event, create a new extended-type
Some standard Media Foundation events also use the extended type to differentiate between types of event data.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an
Receives the event status. If the operation that generated the event was successful, the value is a success code. A failure code means that an error condition triggered the event.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents an event generated by a Media Foundation object. Use this interface to get information about the event.
To get a reference to this interface, call
If you are implementing an object that generates events, call the MFCreateMediaEvent function to create a new event object.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the event type. The event type indicates what happened to trigger the event. It also defines the meaning of the event value.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the extended type of the event.
To define a custom event, create a new extended-type
Some standard Media Foundation events also use the extended type to differentiate between types of event data.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Represents an event generated by a Media Foundation object. Use this interface to get information about the event.
To get a reference to this interface, call
If you are implementing an object that generates events, call the MFCreateMediaEvent function to create a new event object.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves events from any Media Foundation object that generates events.
An object that supports this interface maintains a queue of events. The client of the object can retrieve the events either synchronously or asynchronously. The synchronous method is GetEvent. The asynchronous methods are BeginGetEvent and EndGetEvent.
Applies to: desktop apps | Metro style apps
Retrieves the next event in the queue. This method is synchronous.
Specifies one of the following values.
| Value | Meaning |
|---|---|
| The method blocks until the event generator queues an event. |
| The method returns immediately. |
?
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
| There is a pending request. |
| There are no events in the queue. |
| The object was shut down. |
?
This method executes synchronously.
If the queue already contains an event, the method returns
If dwFlags is 0, the method blocks indefinitely until a new event is queued, or until the event generator is shut down.
If dwFlags is MF_EVENT_FLAG_NO_WAIT, the method fails immediately with the return code MF_E_NO_EVENTS_AVAILABLE.
This method returns MF_E_MULTIPLE_SUBSCRIBERS if you previously called
Applies to: desktop apps | Metro style apps
Begins an asynchronous request for the next event in the queue.
Pointer to the
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
| There is a pending request with the same callback reference and a different state object. |
| There is a pending request with a different callback reference. |
| The object was shut down. |
| There is a pending request with the same callback reference and state object. |
?
When a new event is available, the event generator calls the
Do not call BeginGetEvent a second time before calling EndGetEvent. While the first call is still pending, additional calls to the same object will fail. Also, the
Applies to: desktop apps | Metro style apps
Completes an asynchronous request for the next event in the queue.
Pointer to the
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The object was shut down. |
?
Call this method from inside your application's
Applies to: desktop apps | Metro style apps
Puts a new event in the object's queue.
Specifies the event type. The event type is returned by the event's
The extended type. If the event does not have an extended type, use the value GUID_NULL. The extended type is returned by the event's
A success or failure code indicating the status of the event. This value is returned by the event's
Pointer to a
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The object was shut down. |
?
Applies to: desktop apps | Metro style apps
Provides an event queue for applications that need to implement the
This interface is exposed by a helper object that implements an event queue. If you are writing a component that implements the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the next event in the queue. This method is synchronous.
Call this method inside your implementation of
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Begins an asynchronous request for the next event in the queue.
Call this method inside your implementation of
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Completes an asynchronous request for the next event in the queue.
Call this method inside your implementation of
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Puts an event in the queue.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Shutdown method was called. |
?
Call this method when your component needs to raise an event that contains attributes. To create the event object, call MFCreateMediaEvent. Add attributes to the event by using methods from the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an event, sets a
Call this method inside your implementation of
You can also call this method when your component needs to raise an event that does not contain attributes. If the event data is an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Shutdown method was called. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Creates an event, sets an
Specifies the event type of the event to be added to the queue. The event type is returned by the event's
The extended type of the event. If the event does not have an extended type, use the value GUID_NULL. The extended type is returned by the event's
A success or failure code indicating the status of the event. This value is returned by the event's
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The Shutdown method was called. |
?
Call this method when your component needs to raise an event that contains an
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Shuts down the event queue.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Call this method when your component shuts down. After this method is called, all
This method removes all of the events from the queue.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Represents a list of time ranges, where each range is defined by a start and end time.
The
Several
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of time ranges contained in the object.
Returns the number of time ranges.
This method corresponds to the TimeRanges.length attribute in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the start time for a specified time range.
The zero-based index of the time range to query. To get the number of time ranges, call
Receives the start time, in seconds.
If this method succeeds, it returns
This method corresponds to the TimeRanges.start method in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the end time for a specified time range.
The zero-based index of the time range to query. To get the number of time ranges, call
Receives the end time, in seconds.
If this method succeeds, it returns
This method corresponds to the TimeRanges.end method in HTML5.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Queries whether a specified time falls within any of the time ranges.
The time, in seconds.
Returns TRUE if any time range contained in this object spans the value of the time parameter. Otherwise, returns
This method returns TRUE if the following condition holds for any time range in the list:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Adds a new range to the list of time ranges.
The start time, in seconds.
The end time, in seconds.
If this method succeeds, it returns
If the new range intersects a range already in the list, the two ranges are combined. Otherwise, the new range is added to the list.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Clears the list of time ranges.
If this method succeeds, it returns
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Gets the number of time ranges contained in the object.
This method corresponds to the TimeRanges.length attribute in HTML5.
Applies to: desktop apps | Metro style apps
Represents a description of a media format.
To create a new media type, call MFCreateMediaType.
All of the information in a media type is stored as attributes. To clone a media type, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets the major type of the format.
Receives the major type
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The major type is not set. |
?
This method is equivalent to getting the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the media type is a temporally compressed format. Temporal compression uses information from previously decoded samples when decompressing the current sample.
Receives a Boolean value. The value is TRUE if the format uses temporal compression, or
If this method succeeds, it returns
This method returns
If the method returns TRUE in pfCompressed, it is a hint that the format has temporal compression applied to it. If the method returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Compares two media types and determines whether they are identical. If they are not identical, the method indicates how the two formats differ.
Pointer to the
Receives a bitwise OR of zero or more flags, indicating the degree of similarity between the two media types. The following flags are defined.
| Value | Meaning |
|---|---|
| The major types are the same. The major type is specified by the |
| The subtypes are the same, or neither media type has a subtype. The subtype is specified by the |
| The attributes in one of the media types are a subset of the attributes in the other, and the values of these attributes match, excluding the value of the Specifically, the method takes the media type with the smaller number of attributes and checks whether each attribute from that type is present in the other media type and has the same value (not including To perform other comparisons, use the |
| The user data is identical, or neither media type contains user data. User data is specified by the |
?
The method returns an
| Return code | Description |
|---|---|
| The types are not equal. Examine the pdwFlags parameter to determine how the types differ. |
| | The types are equal. |
| One or both media types are invalid. |
?
Both of the media types must have a major type, or the method returns E_INVALIDARG.
If the method succeeds and all of the comparison flags are set in pdwFlags, the return value is
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves an alternative representation of the media type. Currently only the DirectShow
| Value | Meaning |
|---|---|
| Convert the media type to a DirectShow |
| Convert the media type to a DirectShow |
| Convert the media type to a DirectShow |
| Convert the media type to a DirectShow |
?
Receives a reference to a structure that contains the representation. The method allocates the memory for the structure. The caller must release the memory by calling
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The details of the media type do not match the requested representation. |
| The media type is not valid. |
| The media type does not support the requested representation. |
?
If you request a specific format structure in the guidRepresentation parameter, such as
You can also use the MFInitAMMediaTypeFromMFMediaType function to convert a Media Foundation media type into a DirectShow media type.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Frees memory that was allocated by the
If this method succeeds, it returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets the major type of the format.
This method is equivalent to getting the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Queries whether the media type is a temporally compressed format. Temporal compression uses information from previously decoded samples when decompressing the current sample.
This method returns
If the method returns TRUE in pfCompressed, it is a hint that the format has temporal compression applied to it. If the method returns
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
This topic describes how to implement the
It is rare that you will need to write a custom implementation of the
First, your implementation must inherit the
Second, your object should call
The following code shows a basic implementation of the
///////////////////////////////////////////////////////////////////////////////
// CMyAsyncResult
//
// Custom implementation of null ), m_pState(pState) { *phr = null ; this->pCallback = pCallback; if (pCallback) { this->pCallback->AddRef(); } if (m_pState) { m_pState->AddRef(); } } virtual ~CMyAsyncResult() { SafeRelease(&pCallback); SafeRelease(&m_pState); SafeRelease(&m_pObject); if (m_bLockPlatform) { null ; CMyAsyncResult *pResult = new (std::nothrow) CMyAsyncResult(pCallback, pState, &hr); if (pResult == null ) { return E_OUTOFMEMORY; } if (FAILED(hr)) { delete pResult; return hr; } // If the callback is null , create an event that will be signaled. if (pCallback == null ) { pResult->hEvent = CreateEvent(null , null ); if (pResult->hEvent == null ) { hr = HRESULT_FROM_WIN32(GetLastError()); } } if (SUCCEEDED(hr)) { *ppResult = pResult; // Return the reference to the caller. } else { pResult->Release(); } return hr; } // SetObject: Sets the optional result object. // (This method is not part of the interface.) null ) { return E_POINTER; } *ppunkState = m_pState; if (m_pState) { (*ppunkState)->AddRef(); } return null ) { return E_POINTER; } *ppObject = m_pObject; if (m_pObject) { (*ppObject)->AddRef(); } return null . }
};
Applies to: desktop apps | Metro style apps
Represents a media sample, which is a container object for media data. For video, a sample typically contains one video frame. For audio data, a sample typically contains multiple audio samples, rather than a single sample of audio.
A media sample contains zero or more buffers. Each buffer manages a block of memory, and is represented by the
To create a new media sample, call
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves flags associated with the sample.
Currently no flags are defined. Instead, metadata for samples is defined using attributes. To get attibutes from a sample, use the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets flags associated with the sample.
Currently no flags are defined. Instead, metadata for samples is defined using attributes. To set attibutes on a sample, use the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the presentation time of the sample.
Receives the presentation time, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The sample does not have a presentation time. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the presentation time of the sample.
The presentation time, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
Some pipeline components require samples that have time stamps. Generally the component that generates the data for the sample also sets the time stamp. The Media Session might modify the time stamps.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the duration of the sample.
Receives the duration, in 100-nanosecond units.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The sample does not have a specified duration. |
?
If the sample contains more than one buffer, the duration includes the data from all of the buffers.
If the retrieved duration is zero, or if the method returns MF_E_NO_SAMPLE_DURATION, the duration is unknown. In that case, it might be possible to calculate the duration from the media type?for example, by using the video frame rate or the audio sampling rate.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Sets the duration of the sample.
Duration of the sample, in 100-nanosecond units.
If this method succeeds, it returns
This method succeeds if the duration is negative, although negative durations are probably not valid for most types of data. It is the responsibility of the object that consumes the sample to validate the duration.
The duration can also be zero. This might be valid for some types of data. For example, the sample might contain stream metadata with no buffers.
Until this method is called, the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of buffers in the sample.
Receives the number of buffers in the sample. A sample might contain zero buffers.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Gets a buffer from the sample, by index.
Note??In most cases, it is safer to use the
A sample might contain more than one buffer. Use the GetBufferByIndex method to enumerate the individual buffers.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Converts a sample with multiple buffers into a sample with a single buffer.
Receives a reference to the
If the sample contains more than one buffer, this method copies the data from the original buffers into a new buffer, and replaces the original buffer list with the new buffer. The new buffer is returned in the ppBuffer parameter.
If the sample contains a single buffer, this method returns a reference to the original buffer. In typical use, most samples do not contain multiple buffers.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Adds a buffer to the end of the list of buffers in the sample.
Pointer to the buffer's
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
?
For uncompressed video data, each buffer should contain a single video frame, and samples should not contain multiple frames. In general, storing multiple buffers in a sample is discouraged.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Removes a buffer at a specified index from the sample.
Index of the buffer. To find the number of buffers in the sample, call
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Removes all of the buffers from the sample.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the total length of the valid data in all of the buffers in the sample. The length is calculated as the sum of the values retrieved by the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Copies the sample data to a buffer. This method concatenates the valid data from all of the buffers of the sample, in order.
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| |
| The buffer is not large enough to contain the data. |
?
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves flags associated with the sample.
Currently no flags are defined. Instead, metadata for samples is defined using attributes. To get attibutes from a sample, use the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the presentation time of the sample.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the duration of the sample.
If the sample contains more than one buffer, the duration includes the data from all of the buffers.
If the retrieved duration is zero, or if the method returns MF_E_NO_SAMPLE_DURATION, the duration is unknown. In that case, it might be possible to calculate the duration from the media type?for example, by using the video frame rate or the audio sampling rate.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the number of buffers in the sample.
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Retrieves the total length of the valid data in all of the buffers in the sample. The length is calculated as the sum of the values retrieved by the
This interface is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Begins an asynchronous request to write a media sample to the stream.
When the sample has been written to the stream, the callback object's
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Begins an asynchronous request to write a media sample to the stream.
A reference to the
A reference to the
A reference to the
If this method succeeds, it returns
When the sample has been written to the stream, the callback object's
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps | Metro style apps
Completes an asynchronous request to write a media sample to the stream.
A reference to the
If this method succeeds, it returns
Call this method when the
[This documentation is preliminary and is subject to change.]
These are the API elements for use in desktop apps that are new for Windows?8 Consumer Preview:
For a list of technologies that are new for desktop apps, see Windows 8 Technologies.
For info about the APIs that can be used in Metro style apps, see APIs for Metro style apps.
Applies to: desktop apps | Metro style apps
Implemented by all Media Foundation Transforms (MFTs).
Applies to: desktop apps | Metro style apps
Gets the minimum and maximum number of input and output streams for this Media Foundation transform (MFT).
Receives the minimum number of input streams.
Receives the maximum number of input streams. If there is no maximum, receives the value MFT_STREAMS_UNLIMITED.
Receives the minimum number of output streams.
Receives the maximum number of output streams. If there is no maximum, receives the value MFT_STREAMS_UNLIMITED.
If this method succeeds, it returns
If the MFT has a fixed number of streams, the minimum and maximum values are the same.
It is not recommended to create an MFT that supports zero inputs or zero outputs. An MFT with no inputs or no outputs may not be compatible with the rest of the Media Foundation pipeline. You should create a Media Foundation sink or source for this purpose instead.
When an MFT is first created, it is not guaranteed to have the minimum number of streams. To find the actual number of streams, call
This method should not be called with
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetStreamLimits. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Gets the current number of input and output streams on this Media Foundation transform (MFT).
Receives the number of input streams.
Receives the number of output streams.
If this method succeeds, it returns
The number of streams includes unselected streams?that is, streams with no media type or a
This method should not be called with
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetStreamCount. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Gets the stream identifiers for the input and output streams on this Media Foundation transform (MFT).
Number of elements in the pdwInputIDs array.
Pointer to an array allocated by the caller. The method fills the array with the input stream identifiers. The array size must be at least equal to the number of input streams. To get the number of input streams, call
If the caller passes an array that is larger than the number of input streams, the MFT must not write values into the extra array entries.
Number of elements in the pdwOutputIDs array.
Pointer to an array allocated by the caller. The method fills the array with the output stream identifiers. The array size must be at least equal to the number of output streams. To get the number of output streams, call GetStreamCount.
If the caller passes an array that is larger than the number of output streams, the MFT must not write values into the extra array entries.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. See Remarks. |
| One or both of the arrays is too small. |
?
Stream identifiers are necessary because some MFTs can add or remove streams, so the index of a stream may not be unique. Therefore,
This method can return E_NOTIMPL if both of the following conditions are true:
This method must be implemented if any of the following conditions is true:
All input stream identifiers must be unique within an MFT, and all output stream identifiers must be unique. However, an input stream and an output stream can share the same identifier.
If the client adds an input stream, the client assigns the identifier, so the MFT must allow arbitrary identifiers, as long as they are unique. If the MFT creates an output stream, the MFT assigns the identifier.
By convention, if an MFT has exactly one fixed input stream and one fixed output stream, it should assign the identifier 0 to both streams.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetStreamIDs. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Gets the buffer requirements and other information for an input stream on this Media Foundation transform (MFT).
Input stream identifier. To get the list of stream identifiers, call
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid stream identifier. |
?
It is valid to call this method before setting the media types.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputStreamInfo. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Gets the buffer requirements and other information for an output stream on this Media Foundation transform (MFT).
Output stream identifier. To get the list of stream identifiers, call
Pointer to an
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid stream number. |
?
It is valid to call this method before setting the media types.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputStreamInfo. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Gets the global attribute store for this Media Foundation transform (MFT).
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not support attributes. |
?
Use the
Implementation of this method is optional unless the MFT needs to support a particular set of attributes. Exception: Hardware-based MFTs must implement this method. See Hardware MFTs.
Applies to: desktop apps | Metro style apps
Gets the attribute store for an input stream on this Media Foundation transform (MFT).
Input stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not support input stream attributes. |
| Invalid stream identifier. |
?
Implementation of this method is optional unless the MFT needs to support a particular set of attributes.
To get the attribute store for the entire MFT, call
Applies to: desktop apps | Metro style apps
Gets the attribute store for an output stream on this Media Foundation transform (MFT).
Output stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not support output stream attributes. |
| Invalid stream identifier. |
?
Implementation of this method is optional unless the MFT needs to support a particular set of attributes.
To get the attribute store for the entire MFT, call
Applies to: desktop apps | Metro style apps
Removes an input stream from this Media Foundation transform (MFT).
Identifier of the input stream to remove.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The transform has a fixed number of input streams. |
| The stream is not removable, or the transform currently has the minimum number of input streams it can support. |
| Invalid stream identifier. |
| The transform has unprocessed input buffers for the specified stream. |
?
If the transform has a fixed number of input streams, the method returns E_NOTIMPL.
An MFT might support this method but not allow certain input streams to be removed. If an input stream can be removed, the
If the transform still has unprocessed input for that stream, the method might succeed or it might return MF_E_TRANSFORM_INPUT_REMAINING. If the method succeeds, the MFT will continue to process the remaining input after the stream is removed. If the method returns MF_E_TRANSFORM_INPUT_REMAINING, you must clear the input buffers before removing the stream. To clear the input buffers, either call
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTDeleteInputStream. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Adds one or more new input streams to this Media Foundation transform (MFT).
Number of streams to add.
Array of stream identifiers. The new stream identifiers must not match any existing input streams.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| The MFT has a fixed number of input streams. |
?
If the new streams exceed the maximum number of input streams for this transform, the method returns E_INVALIDARG. To find the maximum number of input streams, call
If any of the new stream identifiers conflicts with an existing input stream, the method returns E_INVALIDARG.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTAddInputStreams. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Gets an available media type for an input stream on this Media Foundation transform (MFT).
Input stream identifier. To get the list of stream identifiers, call
Index of the media type to retrieve. Media types are indexed from zero and returned in approximate order of preference.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not have a list of available input types. |
| Invalid stream identifier. |
| The dwTypeIndex parameter is out of range. |
| You must set the output types before setting the input types. |
?
The MFT defines a list of available media types for each input stream and orders them by preference. This method enumerates the available media types for an input stream. To enumerate the available types, increment dwTypeIndex until the method returns MF_E_NO_MORE_TYPES.
Setting the media type on one stream might change the available types for another stream, or change the preference order. However, an MFT is not required to update the list of available types dynamically. The only guaranteed way to test whether you can set a particular input type is to call
In some cases, an MFT cannot return a list of input types until one or more output types are set. If so, the method returns MF_E_TRANSFORM_TYPE_NOT_SET.
An MFT is not required to implement this method. However, most MFTs should implement this method, unless the supported types are simple and can be discovered through the MFTGetInfo function.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputAvailableType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesIf the MFT stores a media type internally, the MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
Applies to: desktop apps | Metro style apps
Gets an available media type for an output stream on this Media Foundation transform (MFT).
Output stream identifier. To get the list of stream identifiers, call
Index of the media type to retrieve. Media types are indexed from zero and returned in approximate order of preference.
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT does not have a list of available output types. |
| Invalid stream identifier. |
| The dwTypeIndex parameter is out of range. |
| You must set the input types before setting the output types. |
?
The MFT defines a list of available media types for each output stream and orders them by preference. This method enumerates the available media types for an output stream. To enumerate the available types, increment dwTypeIndex until the method returns MF_E_NO_MORE_TYPES.
Setting the media type on one stream can change the available types for another stream (or change the preference order). However, an MFT is not required to update the list of available types dynamically. The only guaranteed way to test whether you can set a particular input type is to call
In some cases, an MFT cannot return a list of output types until one or more input types are set. If so, the method returns MF_E_TRANSFORM_TYPE_NOT_SET.
An MFT is not required to implement this method. However, most MFTs should implement this method, unless the supported types are simple and can be discovered through the MFTGetInfo function.
This method can return a partial media type. A partial media type contains an incomplete description of a format, and is used to provide a hint to the caller. For example, a partial type might include just the major type and subtype GUIDs. However, after the client sets the input types on the MFT, the MFT should generally return at least one complete output type, which can be used without further modification. For more information, see Complete and Partial Media Types.
Some MFTs cannot provide an accurate list of output types until the MFT receives the first input sample. For example, the MFT might need to read the first packet header to deduce the format. An MFT should handle this situation as follows:
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputAvailableType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesIf the MFT stores a media type internally, the MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
Applies to: desktop apps | Metro style apps
Sets, tests, or clears the media type for an input stream on this Media Foundation transform (MFT).
Input stream identifier. To get the list of stream identifiers, call
Pointer to the
Zero or more flags from the _MFT_SET_TYPE_FLAGS enumeration.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The MFT cannot use the proposed media type. |
| Invalid stream identifier. |
| The proposed type is not valid. This error code indicates that the media type itself is not configured correctly; for example, it might contain mutually contradictory attributes. |
| The MFT cannot switch types while processing data. Try draining or flushing the MFT. |
| You must set the output types before setting the input types. |
| The MFT could not find a suitable DirectX Video Acceleration (DXVA) configuration. |
?
This method can be used to set, test without setting, or clear the media type:
Setting the media type on one stream may change the acceptable types on another stream.
An MFT may require the caller to set one or more output types before setting the input type. If so, the method returns MF_E_TRANSFORM_TYPE_NOT_SET.
If the MFT supports DirectX Video Acceleration (DXVA) but is unable to find a suitable DXVA configuration (for example, if the graphics driver does not have the right capabilities), the method should return MF_E_UNSUPPORTED_D3D_TYPE. For more information, see Supporting DXVA 2.0 in Media Foundation.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTSetInputType. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Sets, tests, or clears the media type for an output stream on this Media Foundation transform (MFT).
Output stream identifier. To get the list of stream identifiers, call
Pointer to the
Zero or more flags from the _MFT_SET_TYPE_FLAGS enumeration.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The transform cannot use the proposed media type. |
| Invalid stream identifier. |
| The proposed type is not valid. This error code indicates that the media type itself is not configured correctly; for example, it might contain mutually contradictory flags. |
| The MFT cannot switch types while processing data. Try draining or flushing the MFT. |
| You must set the input types before setting the output types. |
| The MFT could not find a suitable DirectX Video Acceleration (DXVA) configuration. |
?
This method can be used to set, test without setting, or clear the media type:
Setting the media type on one stream may change the acceptable types on another stream.
An MFT may require the caller to set one or more input types before setting the output type. If so, the method returns MF_E_TRANSFORM_TYPE_NOT_SET.
If the MFT supports DirectX Video Acceleration (DXVA) but is unable to find a suitable DXVA configuration (for example, if the graphics driver does not have the right capabilities), the method should return MF_E_UNSUPPORTED_D3D_TYPE. For more information, see Supporting DXVA 2.0 in Media Foundation.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTSetOutputType. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Gets the current media type for an input stream on this Media Foundation transform (MFT).
Input stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid stream identifier. |
| The input media type has not been set. |
?
If the specified input stream does not yet have a media type, the method returns MF_E_TRANSFORM_TYPE_NOT_SET. Most MFTs do not set any default media types when first created. Instead, the client must set the media type by calling
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputCurrentType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesThe MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
Applies to: desktop apps | Metro style apps
Gets the current media type for an output stream on this Media Foundation transform (MFT).
Output stream identifier. To get the list of stream identifiers, call
Receives a reference to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid stream identifier. |
| The output media type has not been set. |
?
If the specified output stream does not yet have a media type, the method returns MF_E_TRANSFORM_TYPE_NOT_SET. Most MFTs do not set any default media types when first created. Instead, the client must set the media type by calling
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputCurrentType. See Creating Hybrid DMO/MFT Objects.
Implementation NotesThe MFT should return a clone of the media type, not a reference to the original type. Otherwise, the caller might modify the type and alter the internal state of the MFT.
Applies to: desktop apps | Metro style apps
Queries whether an input stream on this Media Foundation transform (MFT) can accept more data.
Input stream identifier. To get the list of stream identifiers, call
Receives a member of the _MFT_INPUT_STATUS_FLAGS enumeration, or zero. If the value is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid stream identifier. |
| The media type is not set on one or more streams. |
?
If the method returns the
Use this method to test whether the input stream is ready to accept more data, without incurring the overhead of allocating a new sample and calling ProcessInput.
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output (or both).
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetInputStatus. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Queries whether the Media Foundation transform (MFT) is ready to produce output data.
Receives a member of the _MFT_OUTPUT_STATUS_FLAGS enumeration, or zero. If the value is
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
| The media type is not set on one or more streams. |
?
If the method returns the
MFTs are not required to implement this method. If the method returns E_NOTIMPL, you must call ProcessOutput to determine whether the transform has output data.
If the MFT has more than one output stream, but it does not produce samples at the same time for each stream, it can set the
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputStatus. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Sets the range of time stamps the client needs for output.
Specifies the earliest time stamp. The Media Foundation transform (MFT) will accept input until it can produce an output sample that begins at this time; or until it can produce a sample that ends at this time or later. If there is no lower bound, use the value MFT_OUTPUT_BOUND_LOWER_UNBOUNDED.
Specifies the latest time stamp. The MFT will not produce an output sample with time stamps later than this time. If there is no upper bound, use the value MFT_OUTPUT_BOUND_UPPER_UNBOUNDED.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
| The media type is not set on one or more streams. |
?
This method can be used to optimize preroll, especially in formats that have gaps between time stamps, or formats where the data must start on a sync point, such as MPEG-2. Calling this method is optional, and implementation of this method by an MFT is optional. If the MFT does not implement the method, the return value is E_NOTIMPL.
If an MFT implements this method, it must limit its output data to the range of times specified by hnsLowerBound and hnsUpperBound. The MFT discards any input data that is not needed to produce output within this range. If the sample boundaries do not exactly match the range, the MFT should split the output samples, if possible. Otherwise, the output samples can overlap the range.
For example, suppose the output range is 100 to 150 milliseconds (ms), and the output format is video with each frame lasting 33 ms. A sample with a time stamp of 67 ms overlaps the range (67 + 33 = 100) and is produced as output. A sample with a time stamp of 66 ms is discarded (66 + 33 = 99). Similarly, a sample with a time stamp of 150 ms is produced as output, but a sample with a time stamp of 151 is discarded.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTSetOutputBounds. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Sends an event to an input stream on this Media Foundation transform (MFT).
Input stream identifier. To get the list of stream identifiers, call
Pointer to the
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Not implemented. |
| Invalid stream number. |
| The media type is not set on one or more streams. |
| The pipeline should not propagate the event. |
?
An MFT can handle sending the event downstream, or it can let the pipeline do this, as indicated by the return value:
To send the event downstream, the MFT adds the event to the collection object that is provided by the client in the pEvents member of the
Events must be serialized with the samples that come before and after them. Attach the event to the output sample that follows the event. (The pipeline will process the event first, and then the sample.) If an MFT holds back one or more samples between calls to
If an MFT does not hold back samples and does not need to examine any events, it can return E_NOTIMPL.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessEvent. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Sends a message to the Media Foundation transform (MFT).
The message to send, specified as a member of the
Message parameter. The meaning of this parameter depends on the message type.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid stream number. Applies to the |
| The media type is not set on one or more streams. |
?
Before calling this method, set the media types on all input and output streams.
The MFT might ignore certain message types. If so, the method returns
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessMessage. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps | Metro style apps
Delivers data to an input stream on this Media Foundation transform (MFT).
Input stream identifier. To get the list of stream identifiers, call
Pointer to the
Reserved. Must be zero.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| Invalid argument. |
| Invalid stream identifier. |
| The input sample requires a valid sample duration. To set the duration, call Some MFTs require that input samples have valid durations. Some MFTs do not require sample durations. |
| The input sample requires a time stamp. To set the time stamp, call Some MFTs require that input samples have valid time stamps. Some MFTs do not require time stamps. |
| The transform cannot process more input at this time. |
| The media type is not set on one or more streams. |
| The media type is not supported for DirectX Video Acceleration (DXVA). A DXVA-enabled decoder might return this error code. |
?
Note??If you are converting a DirectX Media Object (DMO) to an MFT, be aware that S_FALSE is not a valid return code for
In most cases, if the method succeeds, the MFT stores the sample and holds a reference count on the
If the MFT already has enough input data to produce an output sample, it does not accept new input data, and ProcessInput returns MF_E_NOTACCEPTING. At that point, the client should clear the pending input data by doing one of the following:
An exception to this rule is the
An MFT can process the input data in the ProcessInput method. However, most MFTs wait until the client calls ProcessOutput.
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output. It should never be in both states or neither state. An MFT should only accept as much input as it needs to generate at least one output sample, at which point ProcessInput returns MF_E_NOTACCEPTING. When ProcessInput returns MF_E_NOTACCEPTING, the client can assume that the MFT is ready to produce output.
If an MFT encounters a non-fatal error in the input data, it can simply drop the data and attempt to recover when it gets the more input data. To request more input data, the MFT returns MF_E_TRANSFORM_NEED_MORE_INPUT from the
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTProcessInput. See Creating Hybrid DMO/MFT Objects.
Asynchronous ProcessingThe previous remarks describe the synchronous processing model. To support asynchronous processing, see Asynchronous MFTs.
Applies to: desktop apps | Metro style apps
Generates output from the current input data.
Bitwise OR of zero or more flags from the _MFT_PROCESS_OUTPUT_FLAGS enumeration.
Number of elements in the pOutputSamples array. The value must be at least 1.
Pointer to an array of
Receives a bitwise OR of zero or more flags from the _MFT_PROCESS_OUTPUT_STATUS enumeration.
The method returns an
| Return code | Description |
|---|---|
| | The method succeeded. |
| The ProcessOutput method was called on an asynchronous MFT that was not expecting this method call. |
| Invalid stream identifier in the dwStreamID member of one or more |
| The transform cannot produce output data until it receives more input data. |
| The format has changed on an output stream, or there is a new preferred format, or there is a new output stream. |
| You must set the media type on one or more streams of the MFT. |
?
Note??If you are converting a DirectX Media Object (DMO) to an MFT, be aware that S_FALSE is not a valid return code for
The size of the pOutputSamples array must be equal to or greater than the number of selected output streams. The number of selected output streams equals the total number of output streams minus the number of deselected streams. A stream is deselected if it has the
This method generates output samples and can also generate events. If the method succeeds, at least one of the following conditions is true:
If MFT_UNIQUE_METHOD_NAMES is defined before including Mftransform.h, this method is renamed MFTProcessOutput. See Creating Hybrid DMO/MFT Objects.
Output BuffersThe MFT returns output data for a stream through the pSample member of the
These flags remain constant unless the media type for the output stream changes.
If the caller allocates the media sample, the media sample must contain a buffer that is large enough to hold the output data. To find the buffer requirements, call GetOutputStreamInfo. The MFT writes the output data to the start of the buffer, overwriting any data that already exists in the buffer.
If the MFT allocates the sample, the MFT also allocates the buffers for the sample.
If the MFT has multiple output streams, the streams might produce output at different rates, so some streams might have output while other streams do not. If a stream did not any produce output, the MFT sets the
If no output streams have data, and the MFT has no events to return, then ProcessOutput returns MF_E_TRANSFORM_NEED_MORE_INPUT.
The MFT cannot return more than one sample per stream in a single call to ProcessOutput. If there is more output data available for a stream after ProcessOutput returns, the MFT sets the
If the MFT has enough data to produce output, it should refuse to accept any more input until ProcessOutput has been called enough times to pull all of the available output. (An exception is when the
The MFT can return a collection of event objects in the pEvents member of each
To send an event to the caller, the MFT performs the following steps inside ProcessOutput:
Events do not have time stamps. The caller should process the events before processing the output samples. In other words, events occur at the point in the stream immediately after the previous call to ProcessOutput, and prior to any output samples returned from the current ProcessOutput call.
It is valid for the ProcessOutput method to return one or more events and zero output samples.
The caller is responsible for releasing any events that the MFT allocates. When the method returns, check the pEvents member of each
// Release the events that an MFT might allocate in(). void ReleaseEventCollection(DWORD cOutputBuffers, * pBuffers) { for (DWORD i = 0; i < cOutputBuffers; i++) { if (pBuffers[i].pEvents) { pBuffers[i].pEvents->Release(); pBuffers[i].pEvents = null ; } } }
An MFT should not use the
The ProcessOutput method can cause any of the following changes in an output stream:
It is possible that all three of these actions will result from a single call to ProcessOutput. The caller must respond to them in the order listed here?first deletions, then additions, then format changes.
The
An input sample might have attributes, which are accessed through the
For a list of sample attributes, see Sample Attributes.
Asynchronous ProcessingThe previous remarks describe the synchronous processing model. To support asynchronous processing, see Asynchronous MFTs.
Applies to: desktop apps | Metro style apps
Gets the global attribute store for this Media Foundation transform (MFT).
Use the
Implementation of this method is optional unless the MFT needs to support a particular set of attributes. Exception: Hardware-based MFTs must implement this method. See Hardware MFTs.
Applies to: desktop apps | Metro style apps
Queries whether the Media Foundation transform (MFT) is ready to produce output data.
If the method returns the
MFTs are not required to implement this method. If the method returns E_NOTIMPL, you must call ProcessOutput to determine whether the transform has output data.
If the MFT has more than one output stream, but it does not produce samples at the same time for each stream, it can set the
After the client has set valid media types on all of the streams, the MFT should always be in one of two states: Able to accept more input, or able to produce more output.
If MFT_UNIQUE_METHOD_NAMES is defined before including mftransform.h, this method is renamed MFTGetOutputStatus. See Creating Hybrid DMO/MFT Objects.
Applies to: desktop apps only
Contains private data for the IDirectXVideoDecoder::Execute method.
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
Applies to: desktop apps only
Contains private data for the IDirectXVideoDecoder::Execute method.
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
[This documentation is preliminary and is subject to change.]
Applies to: desktop apps only
Specifies a range of bytes.
The offset, in bytes, of the start of the range.
The offset, in bytes, of the end of the range.
Applies to: desktop apps only
The
This structure is identical to the DirectShow
Major type
Subtype
If TRUE, samples are of a fixed size. This field is informational only. For audio, it is generally set to TRUE. For video, it is usually TRUE for uncompressed video and
If TRUE, samples are compressed using temporal (interframe) compression. (A value of TRUE indicates that not all frames are key frames.) This field is informational only.
Size of the sample in bytes. For compressed data, the value can be zero.
| Format type | Format structure |
|---|---|
| DVINFO |
| |
| |
| None. |
| |
| |
| |
?
Not used. Set to
Size of the format block of the media type.
Pointer to the format structure. The structure type is specified by the formattype member. The format structure must be present, unless formattype is GUID_NULL or FORMAT_None.
Applies to: desktop apps only
Contains coefficients used to transform multichannel audio into a smaller number of audio channels. This process is called fold-down.
To specify this information in the media type, set the
The ASF media source supports fold-down from six channels (5.1 audio) to two channels (stereo). It gets the information from the g_wszFold6To2Channels3 attribute in the ASF header. This attribute is documented in the Windows Media Format SDK documentation.
Size of the structure, in bytes.
Number of source channels.
Number of destination channels.
Specifies the assignment of audio channels to speaker positions in the transformed audio. This member is a bitwise OR of flags that define the speaker positions. For a list of valid flags, see
Array that contains the fold-down coefficients. The number of coefficients is cSrcChannels?cDstChannels. If the number of coefficients is less than the size of the array, the remaining elements in the array are ignored. For more information about how the coefficients are applied, see Windows Media Audio Professional Codec Features.
Applies to: desktop apps only
Contains private data for the IDirectXVideoDecoder::Execute method.
This structure corresponds to parameters of the IAMVideoAccelerator::Execute method in DirectX Video Acceleration (DXVA) version 1.
Applies to: desktop apps only
Specifies a rectangular area within a video frame.
An
An
Applies to: desktop apps only
Contains one palette entry in a color table.
This union can be used to represent both RGB palettes and Y'Cb'Cr' palettes. The video format that defines the palette determines which union member should be used.
This topic describes how to create a media type that describes an uncompressed video format. For more information about media types generally, see About Media Types.
To create a complete uncompressed video type, set the following attributes on the
Applies to: desktop apps | Metro style apps
Contains information about an output buffer for a Media Foundation transform. This structure is used in the
You must provide an
MFTs can support two different allocation models for output samples:
To find which model the MFT supports for a given output stream, call
| Flag | Allocation Model |
|---|---|
| The MFT allocates the output samples for the stream. Set pSample to | |
| The MFT supports both allocation models. | |
| Neither (default) | The client must allocate the output samples for the stream. |
?
The behavior of ProcessOutput depends on the initial value of pSample and the value of the dwFlags parameter in the ProcessOutput method.
If pSample is
Restriction: This output stream must have the
If pSample is
Restriction: This output stream must have the
If pSample is non-
Restriction: This output stream must not have the
Any other combinations are invalid and cause ProcessOutput to return E_INVALIDARG.
Each call to ProcessOutput can produce zero or more events and up to one sample per output stream.
Applies to: desktop apps | Metro style apps
Contains information about an output stream on a Media Foundation transform (MFT). To get these values, call
Before the media types are set, the only values that should be considered valid is the
After you set a media type on all of the input and output streams (not including optional streams), all of the values returned by the GetOutputStreamInfo method are valid. They might change if you set different media types.
Applies to: desktop apps only
Specifies a rectangular area within a video frame.
An
An
A
Applies to: desktop apps | Metro style apps
Defines a normalized rectangle, which is used to specify sub-rectangles in a video rectangle. When a rectangle N is normalized relative to some other rectangle R, it means the following:
The coordinate (0.0, 0.0) on N is mapped to the upper-left corner of R.
The coordinate (1.0, 1.0) on N is mapped to the lower-right corner of R.
Any coordinates of N that fall outside the range [0...1] are mapped to positions outside the rectangle R. A normalized rectangle can be used to specify a region within a video rectangle without knowing the resolution or even the aspect ratio of the video. For example, the upper-left quadrant is defined as {0.0, 0.0, 0.5, 0.5}.
X-coordinate of the upper-left corner of the rectangle.
Y-coordinate of the upper-left corner of the rectangle.
X-coordinate of the lower-right corner of the rectangle.
Y-coordinate of the lower-right corner of the rectangle.
Applies to: desktop apps | Metro style apps
Initializes Microsoft Media Foundation.
An application must call this function before using Media Foundation. Before your application quits, call
Do not call
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed:
Applies to: desktop apps | Metro style apps
Shuts down the Microsoft Media Foundation platform. Call this function once for every call to
If this function succeeds, it returns
This function is available on the following platforms if the Windows Media Format 11 SDK redistributable components are installed: