連携コールバック関数

マクロ化されていない関数ポインターは PF_InData で提供されますが、それらにアクセスするには提供されたマクロを使用します。マクロの使用を非推奨にすることについて、私たちがどれほど厳格であるかがわかりますか?これは私たちのちょっとした秘密にしましょう。

インタラクションコールバック

Function	Purpose
`PF_ADD_PARAM`	Enumerate your plug-in’s parameters to After Effects during PF_Cmd_PARAM_SETUP, using multiple calls to this function. !!! note Failing to completely clear out a PF_ParamDef prior to PF_ADD_PARAM() can cause many problems. Always use `AEFX_CLR_STRUCT` before adding parameters. PF_Err PF_ADD_PARAM ( PF_InData *in_data, PF_ParamIndex index, PF_ParamDefPtr def); We provide convenience macros for specific parameter types, in Utils/ Param_Utils.h: - `PF_ADD_COLOR` - `PF_ADD_ARBITRARY` - `PF_ADD_SLIDER` - `PF_ADD_FIXED` - `PF_ADD_FLOAT_SLIDERX` - `PF_ADD_CHECKBOXX` - `PF_ADD_BUTTON` - `PF_ADD_ANGLE` - `PF_ADD_NULL` - `PF_ADD_LAYER` - `PF_ADD_255_SLIDER` - `PF_ADD_PERCENT` - `PF_ADD_POINT` - `PF_ADD_POINT_3D` - `PF_ADD_TOPICX` - `PF_END_TOPIC` - `PF_ADD_POPUPX` - `PF_ADD_FLOAT_SLIDERX_DISABLED`
`PF_ABORT`	Returns non-zero if the user has cancelled; return that value to After Effects. Wrap your render routine in a “while abort has not been requested” while loop. PF_Err PF_ABORT (PF_InData *in_data);
`PF_PROGRESS`	Displays a progress bar during processing; current and total describe the percentage complete. Returns non-zero if you should suspend or abort your current processing; return that value to After Effects. Call once per scanline, unless your effect is very slow. If total is `0`, `PF_ABORT` is used instead (presenting the user with different choices). PF_Err PF_PROGRESS ( PF_InData *in_data, A_long current, A_long total );
`PF_CHECKOUT_PARAM`	Obtains parameter values, or the source video layer, at a specified time. After Effects makes caching decisions based on the checkout state of parameters. Allocate a new PF_ParamDef to hold the result; those passed to the plug-in are read-only. If you check out a layer parameter that’s set to `<none>`, the layer returned will be filled with zeros. Masks are not included with checked-out layers. Do not check out layer parameters during UI event handling. PF_Err PF_CHECKOUT_PARAM ( PF_InData in_data, PF_ParamIndex index, A_long what_time, A_long step, A_long time_scale, PF_ParamDef param); If checking out the source layer, a deinterlaced frame will be returned. If you ask for the time that references the upper field, you will receive back the upper field with a filter used to generate the extra scanlines. For example, assuming line 0 and 2 are upper fields, and line 1 is a lower field, if you check out the upper fields, line 0 and 2 will be passed back directly from the source footage, and line 1 will be calculated by averaging lines 0 and 2. If you want to reassemble a full resolution source frame with both fields present, you can call `PF_CHECKOUT_PARAM` twice to get both fields, and reinterlace the footage. What happens when checking out a layer at a time that is not frame-aligned? All items have essentially infinite time resolution, so when asking for a time at any value, AE renders the item at that time. For a composition, that involves interpolating all of the keyframes values to the subframe time. For footage, AE returns a full image that corresponds to the time asked, which is the nearest-to-left frame. If the user has frame-blending on that layer, an interpolated frame is generated.
`PF_CHECKIN_PARAM`	Balance every `PF_CHECKOUT_PARAM`, with a `PF_CHECKIN_PARAM`. Not doing so causes dismal performance and leaks memory. Once checked in, the fields in the PF_ParamDef will no longer be valid. PF_Err PF_CHECKIN_PARAM ( PF_InData in_data, PF_ParamDef param );
`PF_REGISTER_UI`	Register a custom user interface element. See Effect UI & Events. Note: The PF_UIAlignment flags are not honored. PF_Err PF_REGISTER_UI ( PF_InData in_data, PF_CustomUIInfo cust_info );
`PF_CHECKOUT_LAYER_AUDIO`	Given an index, start_time, duration, time_scale, rate, bytes_per_sample, num_channels, and fmt_signed, After Effects will return a corresponding PF_LayerAudio. After Effects will perform any necessary resampling. PF_Err PF_CHECKOUT_LAYER_AUDIO ( PF_InData in_data, PF_ParamIndex index, A_long start_time, A_long duration, A_u_long time_scale, PF_UFixed rate, A_long bytes_per_sample, A_long num_channels, A_long fmt_signed, PF_LayerAudio audio);
`PF_CHECKIN_LAYER_AUDIO`	Balance all calls to PF_CHECKOUT_LAYER_AUDIO, regardless of error conditions, with matching calls to `PF_CHECKIN_LAYER_AUDIO`. PF_Err PF_CHECKIN_LAYER_AUDIO ( PF_InData *in_data, PF_LayerAudio audio );
`PF_GET_AUDIO_DATA`	Returns information about the PF_LayerAudio. All the parameters after audio are optional; pass 0 for any value in which you aren’t interested. rate0 is unsigned, and fmt_signed0 should be non-zero for signed, zero for unsigned. This callback is for visual effects that read audio information. To alter audio, write an audio filter. PF_Err PF_GET_AUDIO_DATA ( PF_InData in_data, PF_LayerAudio audio, PF_SndSamplePtr data0, A_long num_samples0, PF_UFixed rate0, A_long bytes_per_sample0, A_long num_channels0, A_long *fmt_signed0);

パラメータのチェックアウトとパラメータゼロ

エフェクトは、エフェクトコントロール (およびコンポジション) パネル内で 0 から n までの順序で画像に適用されます。

effect[n-1] からの出力は、effect[n] の入力 (param[0]) です。

一方、通常のエフェクトが PF_CHECKOUT_PARAM を使用してレイヤーをチェックアウトすると、順序に関係なく、生の (エフェクトがかかっていない) ソースレイヤを受け取ります。

ただし、SmartFX エフェクトがその入力パラメータ (params[0]) をチェックアウトすると、以前のエフェクトが * 適用されます。

パラメータのチェックアウト動作

レイヤーのインポイントとアウトポイントがトリミングされているかどうかに関係なく、ソースフッテージの開始から終了まで有効なフレームが取得され、その前後が透明になります。

チェックアウトされているコンポジションよりも低いフレームレートを持つレイヤーパラメータは、低いフレームレートで必要な頻度でのみ更新されます。

30fps コンポジションでチェックアウトされた 10fps レイヤーは、3 フレームごとに更新するだけで済みます。静的な入力レイヤーにもかかわらず、エフェクトの出力をフレームごとに変更したい場合は、PF_Outflag_NON_PARAM_VARY を設定する必要があります。

エフェクトが継続的にラスタライズされた Adobe Illustrator レイヤーをチェックアウトすると、After Effects は、ジオメトリが適用された Illustrator レイヤーをコンポジションサイズのバッファーにレンダリングします。

パラメータのチェックアウトと再入

異なる時点でレイヤーをチェックアウトするプラグインは、リエントラント動作を生成する可能性があります。 Checkout サンプルプラグインがコンポジション B のレイヤーに適用され、B がコンポジション A にプリコンポーズされ、そこに Checkout も適用されるインスタンスを考えてみましょう。

コンポジション A がレンダリングされると、Checkout[A] に PF_Cmd_RENDER が送信され、その間に現在の時間以外の時間からレイヤー (コンポジション B) がチェックアウトされます。

チェックアウトされたレイヤーを提供するために、After Effects は PF_Cmd_RENDER を Checkout[B] に送信します。

さあ、再帰！

パラメータをチェックアウトする場合、エフェクトは再入可能なレンダーリクエストを適切に処理する必要があります。

グローバルを使用したり、静的変数を読み書きしたりしないでください…でも、とにかくそうするつもりはありませんでしたよね?

反復中の進行状況

After Effects は、レンダリング中であっても、ユーザーのインタラクションに可能な限り応答するよう努めます。。 PF_ITERATE() を適切に使用して、同じことを行います。たとえば、PF_Cmd_RENDER への応答中に PF_ITERATE 関数を 3 回使用しているとします。

この場合、次のように始めることになります。

lines_per_iterateL = in_data>extent_hint.top - in_data>extent_hint.bottom;
total_linesL = 3 * lines_per_iterateL;
lines_so_farL = 0;

各反復の後、すでに完了した行を現在の位置に追加します。

suites.iterate8suite()>iterate( lines_so_farL,
                                total_linesL,
                                input_worldP,
                                &output>extent_hint,
                                refcon,
                                WhizBangPreProcessFun,
                                output_worldP);

lines_so_farL += lines_per_iterateL;

ERR(PF_PROGRESS(lines_so_farL, total_linesL));

suites.iterate8suite()>iterate( lines_so_farL,
                                total_linesL,
                                input_worldP,
                                &output>extent_hint,
                                refcon,
                                WhizBangRenderFunc,
                                output_worldP);

lines_so_far += lines_per_iterateL;

ERR(PF_PROGRESS(lines_so_farL, total_linesL));

suites.iterate8suite()>iterate( lines_so_farL,
                                total_linesL,
                                input_worldP,
                                &output>extent_hint,
                                refcon,
                                WhizBangPostProcessFunc,
                                output_worldP);

ERR(PF_PROGRESS(lines_so_farL, total_linesL));