IWICBitmapCodecProgressNotification (デコーダー) の実装
IWICBitmapCodecProgressNotification
コーデックが大きなイメージで CopyPixels などの I/O 操作を実行している場合、完了までに数秒または数分かかる場合があります。 エンド ユーザーが実行時間の長い操作を中断できない場合は、アプリケーションがハングしていると考える場合があります。 ユーザーは多くの場合、アプリケーションが応答しなくなると、コンピューターの制御を回復しようとして、アプリケーションを閉じるか、コンピューターを再起動します。
このインターフェイスを使用すると、アプリケーションは、コーデックが指定した間隔で呼び出すことができるコールバック関数を指定して、現在の操作の進行状況を呼び出し元に通知できます。 アプリケーションは、このコールバック関数を使用して、操作の状態をユーザーに通知する進行状況をユーザー インターフェイスに表示できます。 ユーザーが [進行状況] ダイアログ ボックスの [キャンセル] ボタンをクリックすると、アプリケーションはコールバック関数からWINCODEC_ERR_ABORTEDを返します。 この場合、コーデックは指定した操作をキャンセルし、この HRESULT を操作を実行していたメソッドの呼び出し元に反映する必要があります。
このインターフェイスは、コンテナー レベルのデコーダー クラスに実装する必要があります。
interface IWICBitmapCodecProgressNotification : public IUnknown
{
HRESULT RegisterProgressNotification (
PFNProgressNotification pfnProgressNotification,
LPVOID pvData,
DWORD dwProgressFlags );
}
RegisterProgressNotification
RegisterProgressNotification は、コーデックが指定した間隔で呼び出すことができるコールバック関数を登録するために、アプリケーションによって呼び出されます。 最初のパラメーター pfnProgressNotification は、コーデックが定期的に呼び出すコールバック関数へのポインターです。
pvData パラメーターは、コールバック関数が呼び出されるたびに、呼び出し元がコーデックをコールバック関数に戻す必要があるオブジェクトを指します。 このオブジェクトは何でもかまいませんが、コーデックにとって特に重要な意味はありません。
dwProgressFlags パラメーターは、コーデックがコールバック関数を呼び出すタイミングを指定します。 OR 関数は、このパラメーターに対して 2 つの列挙を使用して実行できます。 WICProgressOperation 列挙型は、デコード中にコールバック関数を呼び出す (WICProgressOperationCopyPixels)、エンコード (WICProgersOperationWritePixels)、またはその両方 (WICProgressOperationAll) を呼び出すかどうかを指定します。
enum WICProgressOperation
{
WICProgressOperationCopyPixels,
WICProgerssOperationWritePixels,
WICProgressOperationAll
};
コーデックは、操作全体を通して一定の間隔でコールバック関数を呼び出す必要がありますが、呼び出し元は特定の要件を指定できます。 WICProgressNotification 列挙型は、操作のどの時点でコールバック関数を呼び出すかを示します。 呼び出し元が WICProgressNotificationBegin を指定する場合は、操作の開始時に呼び出す必要があります (0.0)。 呼び出し元がこれを指定しない場合は省略可能です。 同様に、呼び出し元が WICProgerssNotificationEnd を指定する場合は、操作が完了したときに呼び出す必要があります (1.0)。 呼び出し元が WICProgressNotificationAll を指定する場合は、最初と最後だけでなく、操作全体の一定の間隔で呼び出す必要があります。 呼び出し元は WICProgersNotificationFrequent を指定することもできます。これは、2 行のスキャン行ごとに頻繁に呼び出されることを示します。 (呼び出し元は通常、非常に大きなイメージに対してのみこのフラグを使用します)。それ以外の場合は、通常、処理するスキャン行の合計数の約 10% ずつの間隔でコールバックする必要があります。
enum WICProgressNotification
{
WICProgressNotificationBegin,
WICProgerssNotificationEnd,
WICProgerssNotificationFrequent,
WICProgressNotificationAll
};
特定のデコーダーまたはエンコーダー インスタンスに登録できるコールバック関数は、一度に 1 つだけです。 アプリケーションが RegisterProgressNotification を複数回呼び出す場合は、以前に登録したコールバック関数を新しいコールバック関数に置き換えます。 コールバック登録を取り消すために、呼び出し元は pfnProgressNotification パラメーターを NULL に設定 します。
PFNProgressNotification
PFNProgressNotification は、次のシグネチャを持つコールバック関数です。
typedef HRESULT (*PFNProgressNotification) (
LPVOID pvData,
ULONG uFrameNum,
WICProgressOperation operation,
double dblProgress );
コールバック関数を呼び出すときは、 pvData パラメーターを使用して、アプリケーションがコールバック関数を登録したときに指定したのと同じ pvData を返します。
uFrameNum パラメーターは、処理中のフレームのインデックスを示す必要があります。
デコード時に操作パラメーターを WICProgressOperationCopyPixels に設定し、エンコード時に WICProgressOperationWritePixels を設定します。
dblProgress パラメーターには、0.0 (操作の開始) から 1.0 (操作の完了) の間の数値を指定する必要があります。 この値は、処理されるスキャン行の合計数に対して既に処理されているスキャン行の割合を反映している必要があります。
関連トピック
-
リファレンス
-
概念