MFTEnumEx

関数

条件に合致するMFT変換器をアクティブ形式で列挙する。

DLLMFPlat.dll呼出規約winapi対応OSWindows 7 以降

シグネチャ

// MFPlat.dll
#include <windows.h>

HRESULT MFTEnumEx(
    GUID guidCategory,
    DWORD Flags,
    const MFT_REGISTER_TYPE_INFO* pInputType,   // optional
    const MFT_REGISTER_TYPE_INFO* pOutputType,   // optional
    IMFActivate*** pppMFTActivate,
    DWORD* pnumMFTActivate
);

パラメーター

名前	型	方向	説明
guidCategory	GUID	in	列挙する MFT のカテゴリを指定する GUID。MFT カテゴリの一覧については、MFT_CATEGORY を参照してください。
Flags	DWORD	in	_MFT_ENUM_FLAG 列挙体のフラグを 0 個以上ビットごとの OR で組み合わせた値。
pInputType	MFT_REGISTER_TYPE_INFO*	inoptional	一致させる入力メディアタイプを指定する MFT_REGISTER_TYPE_INFO 構造体へのポインター。このパラメーターは NULL でもかまいません。NULL の場合、すべての入力タイプが一致対象になります。
pOutputType	MFT_REGISTER_TYPE_INFO*	inoptional	一致させる出力メディアタイプを指定する MFT_REGISTER_TYPE_INFO 構造体へのポインター。このパラメーターは NULL でもかまいません。NULL の場合、すべての出力タイプが一致対象になります。
pppMFTActivate	IMFActivate***	out	IMFActivate インターフェイスポインターの配列を受け取ります。各ポインターは、検索条件に一致する MFT のアクティベーションオブジェクトを表します。この配列のメモリは関数が割り当てます。呼び出し側は、これらのポインターを解放し、CoTaskMemFree 関数を呼び出して配列のメモリを解放する必要があります。
pnumMFTActivate	DWORD*	out	pppMFTActivate 配列の要素数を受け取ります。検索条件に一致する MFT がない場合、このパラメーターは値 0 を受け取ります。

戻り値の型: HRESULT

公式ドキュメント

指定した検索条件に一致する Microsoft Media Foundation トランスフォーム (MFT) の一覧を取得します。この関数は MFTEnum 関数を拡張したものです。

戻り値

この関数が成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

Flags パラメーターは、どの MFT を列挙するか、およびそれらを返す順序を制御します。このパラメーターのフラグはいくつかのグループに分かれます。

最初のフラグのグループは、MFT がデータを処理する方法を指定します。

フラグ	説明
MFT_ENUM_FLAG_SYNCMFT	MFT はソフトウェアで同期的にデータを処理します。これは元の MFT 処理モデルであり、Windows Vista と互換性があります。
MFT_ENUM_FLAG_ASYNCMFT	MFT はソフトウェアで非同期的にデータを処理します。この処理モデルには Windows 7 が必要です。詳細については、Asynchronous MFTs を参照してください。
MFT_ENUM_FLAG_HARDWARE	MFT は、AVStream ドライバーまたは GPU ベースのプロキシ MFT を使用して、ハードウェアベースのデータ処理を行います。このカテゴリの MFT は常にデータを非同期的に処理します。詳細については、Hardware MFTs を参照してください。

すべての MFT は、これらのカテゴリのいずれか 1 つに正確に該当します。あるカテゴリを列挙するには、Flags パラメーターで対応するフラグを設定します。複数のカテゴリを列挙するために、これらのフラグを組み合わせることができます。これらのフラグがいずれも指定されない場合、既定のカテゴリは同期 MFT (MFT_ENUM_FLAG_SYNCMFT) になります。

次に、以下のフラグは、通常は結果から除外される MFT を含めます。既定では、これらの条件に一致するものは結果から除外されます。これらを含めるには、以下のいずれかのフラグを使用します。

フラグ	説明
MFT_ENUM_FLAG_FIELDOFUSE	アプリケーションによるロック解除が必要な MFT を含めます。
MFT_ENUM_FLAG_LOCALMFT	MFTRegisterLocal 関数または MFTRegisterLocalByCLSID 関数を通じて、呼び出し側のプロセス内に登録された MFT を含めます。
MFT_ENUM_FLAG_TRANSCODE_ONLY	再生ではなくトランスコードに最適化された MFT を含めます。

最後のフラグは、結果の並べ替えとフィルター処理に使用されます。

フラグ	説明
MFT_ENUM_FLAG_SORTANDFILTER	結果を並べ替えてフィルター処理します。

MFT_ENUM_FLAG_SORTANDFILTER フラグが設定されている場合、MFTEnumEx 関数は次のように結果を並べ替えます。

ローカル: MFT_ENUM_FLAG_LOCALMFT フラグが設定されている場合、ローカル MFT がリストの先頭に表示されます。ローカル MFT を登録するには、MFTRegisterLocal 関数または MFTRegisterLocalByCLSID 関数を呼び出します。
メリット: メリット値を持つ MFT が次にリストに表示され、メリット値の高い順 (最高から最低) に並びます。メリットの詳細については、MFT_CODEC_MERIT_Attribute を参照してください。
優先: MFT がプラグインコントロールの優先リストに登録されている場合、次にリストに表示されます。プラグインコントロールの詳細については、IMFPluginControl を参照してください。
MFT がブロックリストに登録されている場合、結果から除外されます。ブロックリストの詳細については、IMFPluginControl::IsDisabled を参照してください。
検索条件に一致するその他の MFT は、並べ替えされずにリストの末尾に表示されます。

MFT_ENUM_FLAG_SORTANDFILTER フラグを設定しない場合、MFTEnumEx 関数は並べ替えされていないリストを返します。

Flags パラメーターを 0 に設定することは、値 MFT_ENUM_FLAG_SYNCMFT | MFT_ENUM_FLAG_LOCALMFT | MFT_ENUM_FLAG_SORTANDFILTER を使用することと同じです。

Flags を MFT_ENUM_FLAG_SYNCMFT に設定することは、MFTEnum 関数を呼び出すことと同じです。

検索条件に一致する MFT がない場合、他のエラーが発生しない限り、この関数は S_OK を返します。したがって、pppMFTActivate ポインターを逆参照する前に、必ず pcMFTActivate パラメーターで受け取った数を確認してください。

注意ローカル MFT だけを列挙し、それ以外を列挙しない方法はありません。Flags を MFT_ENUM_FLAG_LOCALMFT に設定することは、MFT_ENUM_FLAG_SYNCMFT フラグを含めることと同じです。ただし、MFT_ENUM_FLAG_SORTANDFILTER フラグを指定して結果を並べ替えると、ローカル MFT がリストの先頭に表示されます。

MFT の作成

少なくとも 1 つの MFT が検索条件に一致する場合、pppMFTActivate パラメーターは IMFActivate ポインターの配列を受け取ります。一致した MFT ごとに 1 つのポインターが返されます。各ポインターは、その MFT のアクティベーションオブジェクトを表します。詳細については、Activation Objects を参照してください。

各 MFT に関する追加情報は、アクティベーションオブジェクトの属性として格納されます。設定できる属性の一覧については、Transform Attributes を参照してください。

MFT のインスタンスを作成するには、IMFActivate::ActivateObject を呼び出します。

ハードウェアコーデック

次のレジストリキーが 0 に設定されている場合、ハードウェアコーデックは列挙結果から除外されます。

デコーダー: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Media Foundation\HardwareMFT\EnableDecoders

エンコーダー: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Media Foundation\HardwareMFT\EnableEncoders

ビデオプロセッサ: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Media Foundation\HardwareMFT\EnableVideoProcessors

これらのキーは OEM 向けであり、アプリケーションで使用すべきではありません。

ハードウェアコーデックの場合、MFTEnumEx の guidCategory パラメーターには、次のカーネルストリーミング (KS) デバイスカテゴリのいずれかを指定することもできます。

KSCATEGORY_DATACOMPRESSOR
KSCATEGORY_DATADECOMPRESSOR

ハードウェアコーデックは MFT_CATEGORY GUID の下にも登録すべきであるため、アプリケーションは通常、KS デバイスカテゴリではなくこれらのカテゴリを使用してください。

例

次の例は、ビデオまたはオーディオのデコーダーを検索します。非同期、ハードウェア、トランスコード、および使用分野 (field-of-use) のデコーダーは除外されます。一致が見つかった場合、このコードはリストの最初の MFT を作成します。

HRESULT FindDecoderEx(
    const GUID& subtype,        // Subtype
    BOOL bAudio,                // TRUE for audio, FALSE for video
    IMFTransform **ppDecoder    // Receives a pointer to the decoder.
    )
{
    HRESULT hr = S_OK;
    UINT32 count = 0;

    IMFActivate **ppActivate = NULL;

    MFT_REGISTER_TYPE_INFO info = { 0 };

    info.guidMajorType = bAudio ? MFMediaType_Audio : MFMediaType_Video;
    info.guidSubtype = subtype;

    hr = MFTEnumEx(
        bAudio ? MFT_CATEGORY_AUDIO_DECODER : MFT_CATEGORY_VIDEO_DECODER,
        MFT_ENUM_FLAG_SYNCMFT | MFT_ENUM_FLAG_LOCALMFT | MFT_ENUM_FLAG_SORTANDFILTER,
        &info,      // Input type
        NULL,       // Output type
        &ppActivate,
        &count
        );

    if (SUCCEEDED(hr) && count == 0)
    {
        hr = MF_E_TOPO_CODEC_NOT_FOUND;
    }

    // Create the first decoder in the list.

    if (SUCCEEDED(hr))
    {
        hr = ppActivate[0]->ActivateObject(IID_PPV_ARGS(ppDecoder));
    }

    for (UINT32 i = 0; i < count; i++)
    {
        ppActivate[i]->Release();
    }
    CoTaskMemFree(ppActivate);

    return hr;
}

次の例は、ビデオまたはオーディオのエンコーダーを検索します。非同期、ハードウェア、トランスコード、および使用分野 (field-of-use) のエンコーダーは除外されます。

HRESULT FindEncoderEx(
    const GUID& subtype,        // Subtype
    BOOL bAudio,                // TRUE for audio, FALSE for video
    IMFTransform **ppEncoder    // Receives a pointer to the decoder.
    )
{
    HRESULT hr = S_OK;
    UINT32 count = 0;

    IMFActivate **ppActivate = NULL;

    MFT_REGISTER_TYPE_INFO info = { 0 };

    info.guidMajorType = bAudio ? MFMediaType_Audio : MFMediaType_Video;
    info.guidSubtype = subtype;

    hr = MFTEnumEx(
        bAudio ? MFT_CATEGORY_AUDIO_ENCODER : MFT_CATEGORY_VIDEO_ENCODER,
        MFT_ENUM_FLAG_SYNCMFT | MFT_ENUM_FLAG_LOCALMFT | MFT_ENUM_FLAG_SORTANDFILTER,
        NULL,       // Input type
        &info,      // Output type
        &ppActivate,
        &count
        );

    if (SUCCEEDED(hr) && count == 0)
    {
        hr = MF_E_TOPO_CODEC_NOT_FOUND;
    }

    // Create the first encoder in the list.

    if (SUCCEEDED(hr))
    {
        hr = ppActivate[0]->ActivateObject(IID_PPV_ARGS(ppEncoder));
    }

    for (UINT32 i = 0; i < count; i++)
    {
        ppActivate[i]->Release();
    }
    CoTaskMemFree(ppActivate);

    return hr;
}

次の例は、非同期、ハードウェア、またはトランスコードのデコーダーを含めるオプション付きで、ビデオデコーダーを検索します。

HRESULT FindVideoDecoder(
    const GUID& subtype,
    BOOL bAllowAsync,
    BOOL bAllowHardware, 
    BOOL bAllowTranscode,
    IMFTransform **ppDecoder
    )
{
    HRESULT hr = S_OK;
    UINT32 count = 0;

    IMFActivate **ppActivate = NULL;

    MFT_REGISTER_TYPE_INFO info = { MFMediaType_Video, subtype };

    UINT32 unFlags = MFT_ENUM_FLAG_SYNCMFT  | MFT_ENUM_FLAG_LOCALMFT | 
                     MFT_ENUM_FLAG_SORTANDFILTER;

    if (bAllowAsync)
    {
        unFlags |= MFT_ENUM_FLAG_ASYNCMFT;
    }
    if (bAllowHardware)
    {
        unFlags |= MFT_ENUM_FLAG_HARDWARE;
    }
    if (bAllowTranscode)
    {
        unFlags |= MFT_ENUM_FLAG_TRANSCODE_ONLY;
    }

    hr = MFTEnumEx(MFT_CATEGORY_VIDEO_DECODER,
        unFlags,
        &info,      // Input type
        NULL,       // Output type
        &ppActivate,
        &count);
  
    if (SUCCEEDED(hr) && count == 0)
    {
        hr = MF_E_TOPO_CODEC_NOT_FOUND;
    }

    // Create the first decoder in the list.
    if (SUCCEEDED(hr))
    {
        hr = ppActivate[0]->ActivateObject(IID_PPV_ARGS(ppDecoder));
    }

    for (UINT32 i = 0; i < count; i++)
    {
        ppActivate[i]->Release();
    }
    CoTaskMemFree(ppActivate);

    return hr;
}

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// MFPlat.dll
#include <windows.h>

HRESULT MFTEnumEx(
    GUID guidCategory,
    DWORD Flags,
    const MFT_REGISTER_TYPE_INFO* pInputType,   // optional
    const MFT_REGISTER_TYPE_INFO* pOutputType,   // optional
    IMFActivate*** pppMFTActivate,
    DWORD* pnumMFTActivate
);

[DllImport("MFPlat.dll", ExactSpelling = true)]
static extern int MFTEnumEx(
    Guid guidCategory,   // GUID
    uint Flags,   // DWORD
    IntPtr pInputType,   // MFT_REGISTER_TYPE_INFO* optional
    IntPtr pOutputType,   // MFT_REGISTER_TYPE_INFO* optional
    IntPtr pppMFTActivate,   // IMFActivate*** out
    out uint pnumMFTActivate   // DWORD* out
);

<DllImport("MFPlat.dll", ExactSpelling:=True)>
Public Shared Function MFTEnumEx(
    guidCategory As Guid,   ' GUID
    Flags As UInteger,   ' DWORD
    pInputType As IntPtr,   ' MFT_REGISTER_TYPE_INFO* optional
    pOutputType As IntPtr,   ' MFT_REGISTER_TYPE_INFO* optional
    pppMFTActivate As IntPtr,   ' IMFActivate*** out
    <Out> ByRef pnumMFTActivate As UInteger   ' DWORD* out
) As Integer
End Function

' guidCategory : GUID
' Flags : DWORD
' pInputType : MFT_REGISTER_TYPE_INFO* optional
' pOutputType : MFT_REGISTER_TYPE_INFO* optional
' pppMFTActivate : IMFActivate*** out
' pnumMFTActivate : DWORD* out
Declare PtrSafe Function MFTEnumEx Lib "mfplat" ( _
    ByVal guidCategory As LongPtr, _
    ByVal Flags As Long, _
    ByVal pInputType As LongPtr, _
    ByVal pOutputType As LongPtr, _
    ByVal pppMFTActivate As LongPtr, _
    ByRef pnumMFTActivate As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

MFTEnumEx = ctypes.windll.mfplat.MFTEnumEx
MFTEnumEx.restype = ctypes.c_int
MFTEnumEx.argtypes = [
    ctypes.c_void_p,  # guidCategory : GUID
    wintypes.DWORD,  # Flags : DWORD
    ctypes.c_void_p,  # pInputType : MFT_REGISTER_TYPE_INFO* optional
    ctypes.c_void_p,  # pOutputType : MFT_REGISTER_TYPE_INFO* optional
    ctypes.c_void_p,  # pppMFTActivate : IMFActivate*** out
    ctypes.POINTER(wintypes.DWORD),  # pnumMFTActivate : DWORD* out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('MFPlat.dll')
MFTEnumEx = Fiddle::Function.new(
  lib['MFTEnumEx'],
  [
    Fiddle::TYPE_VOIDP,  # guidCategory : GUID
    -Fiddle::TYPE_INT,  # Flags : DWORD
    Fiddle::TYPE_VOIDP,  # pInputType : MFT_REGISTER_TYPE_INFO* optional
    Fiddle::TYPE_VOIDP,  # pOutputType : MFT_REGISTER_TYPE_INFO* optional
    Fiddle::TYPE_VOIDP,  # pppMFTActivate : IMFActivate*** out
    Fiddle::TYPE_VOIDP,  # pnumMFTActivate : DWORD* out
  ],
  Fiddle::TYPE_INT)

#[link(name = "mfplat")]
extern "system" {
    fn MFTEnumEx(
        guidCategory: GUID,  // GUID
        Flags: u32,  // DWORD
        pInputType: *const MFT_REGISTER_TYPE_INFO,  // MFT_REGISTER_TYPE_INFO* optional
        pOutputType: *const MFT_REGISTER_TYPE_INFO,  // MFT_REGISTER_TYPE_INFO* optional
        pppMFTActivate: *mut *mut *mut core::ffi::c_void,  // IMFActivate*** out
        pnumMFTActivate: *mut u32  // DWORD* out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("MFPlat.dll")]
public static extern int MFTEnumEx(Guid guidCategory, uint Flags, IntPtr pInputType, IntPtr pOutputType, IntPtr pppMFTActivate, out uint pnumMFTActivate);
"@
$api = Add-Type -MemberDefinition $sig -Name 'MFPlat_MFTEnumEx' -Namespace Win32 -PassThru
# $api::MFTEnumEx(guidCategory, Flags, pInputType, pOutputType, pppMFTActivate, pnumMFTActivate)

#uselib "MFPlat.dll"
#func global MFTEnumEx "MFTEnumEx" sptr, sptr, sptr, sptr, sptr, sptr
; MFTEnumEx guidCategory, Flags, varptr(pInputType), varptr(pOutputType), pppMFTActivate, varptr(pnumMFTActivate)   ; 戻り値は stat
; guidCategory : GUID -> "sptr"
; Flags : DWORD -> "sptr"
; pInputType : MFT_REGISTER_TYPE_INFO* optional -> "sptr"
; pOutputType : MFT_REGISTER_TYPE_INFO* optional -> "sptr"
; pppMFTActivate : IMFActivate*** out -> "sptr"
; pnumMFTActivate : DWORD* out -> "sptr"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "MFPlat.dll"
#cfunc global MFTEnumEx "MFTEnumEx" int, int, var, var, sptr, var
; res = MFTEnumEx(guidCategory, Flags, pInputType, pOutputType, pppMFTActivate, pnumMFTActivate)
; guidCategory : GUID -> "int"
; Flags : DWORD -> "int"
; pInputType : MFT_REGISTER_TYPE_INFO* optional -> "var"
; pOutputType : MFT_REGISTER_TYPE_INFO* optional -> "var"
; pppMFTActivate : IMFActivate*** out -> "sptr"
; pnumMFTActivate : DWORD* out -> "var"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "MFPlat.dll"
#cfunc global MFTEnumEx "MFTEnumEx" int, int, sptr, sptr, sptr, sptr
; res = MFTEnumEx(guidCategory, Flags, varptr(pInputType), varptr(pOutputType), pppMFTActivate, varptr(pnumMFTActivate))
; guidCategory : GUID -> "int"
; Flags : DWORD -> "int"
; pInputType : MFT_REGISTER_TYPE_INFO* optional -> "sptr"
; pOutputType : MFT_REGISTER_TYPE_INFO* optional -> "sptr"
; pppMFTActivate : IMFActivate*** out -> "sptr"
; pnumMFTActivate : DWORD* out -> "sptr"
; ※値渡し構造体は直接渡せません。intにパック、または var で構造体変数を渡してください。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。