afterpresets 0.2.0 → 0.3.0

package/template/native/README.md

@@ -0,0 +1,71 @@
+# __EXTENSION_NAME__
+
+An After Effects effect plugin built with [AfterPresets](https://afterpresets.com).
+Bundle ID: `__BUNDLE_ID__` (permanent).
+
+You do not need to write code. Open this folder in an AI agent (the Code tab
+of the Claude desktop app, Claude Code, Codex, Cursor...) and describe the
+effect you want. The agent follows `AGENTS.md`, builds the plugin, puts it
+into After Effects, and tests it there.
+
+## Start
+
+1. Tell your agent: "Read AGENTS.md and finish the setup." It checks the
+   build tools and asks you for the few things it cannot do itself:
+   - downloading Adobe's After Effects SDK once (it needs your free Adobe ID),
+   - approving a one-time macOS password prompt for the plugin folder,
+   - restarting After Effects when you have unsaved work.
+
+2. In After Effects, apply **Effect → AfterPresets → __EXTENSION_NAME__** to a
+   layer. The starter tints the layer toward a colour (Tint, Screen or
+   Multiply), optionally fading across the layer.
+
+3. Tell your agent what to build. Things you can type:
+
+   - "Make this a glow: radius, intensity and colour. Show me frames."
+   - "Add a Softness slider and test it at 8 and 16 bits."
+   - "Turn licensing off; this effect is free."
+   - "Check everything and push a test release."
+
+Prefer a terminal? `npx ap dev` builds, installs and rebuilds on every save.
+
+## Publish
+
+Ask your agent ("push a test release", "publish it to everyone") or type:
+
+| Command | What it does |
+| --- | --- |
+| `npx ap build` | Release ZIP in `dist/` with buyer install scripts: both versions on a Mac (macOS `.plugin` + Windows `.aex`), the Windows `.aex` only on a Windows PC |
+| `npx ap push --channel test` | Release to your testers only |
+| `npx ap push --channel production` | Release to everyone |
+| `npx ap releases rollback 1.1.0` | Go back to an earlier version |
+
+Buyers run `mac-install.command` or `windows-install.bat` from the ZIP once;
+updates then install themselves at the next After Effects start. They sign
+in from the effect's **Options** (or its **License...** button) in the
+Effect Controls panel.
+
+## Project map
+
+How a new project starts. Your agent keeps an overview of the effect it
+builds in `AGENTS.md` ("Project overview").
+
+| Path | What it is |
+| --- | --- |
+| `afterpresets.json` | Name, bundle ID, version (`ap push` bumps it), `"platform": "native"` |
+| `effect.json` | The effect: menu name, `matchName` (permanent), category, parameters (permanent `id`s), license and update options, flags. The PiPL resource and the generated headers come from it |
+| `src/Effect.cpp` | After Effects entry points: setup, parameters, Smart Render, Options |
+| `src/Render.h` | The pixel work (8/16/32 bits per channel) |
+| `src/License.cpp`, `src/License.h` | AfterPresets licensing, the Options dialog and the update notice (`ap_native`) |
+| `vendor/ap_native/` | AfterPresets native runtime; copied by `ap init` / `ap upgrade`, do not edit |
+| `native.cmake` | Optional: extra libraries or compiler settings (CMake), included last |
+| `build/` | Build output and the generated `ap_effect_config.h` / `ap_effect_params.h` (not committed) |
+| `dist/` | Release ZIPs from `ap build` (not committed) |
+| `docs/initial_setup.md` | One-time computer and agent setup, ending with "what should it do?" |
+| `docs/code_guide.md` | How the project is organised: `effect.json`, licensing, updates, installing |
+| `docs/release_checklist.md` | What to check before the first production release |
+| `docs/afterpresets/` | Agent reference: rules, testing, debugging, Adobe's SDK guide (generated) |
+| `AGENTS.md` | Instructions for coding agents, and the effect overview they keep current |
+
+Adobe's SDK is not part of this project: it lives once per computer in
+`~/.afterpresets/sdk/`. Never commit it.

package/template/native/docs/code_guide.md

@@ -0,0 +1,72 @@
+# Code guide
+
+How this project is organised. Read it before changing `effect.json`,
+licensing or updates. The SDK rules are in `docs/afterpresets/rules.md`.
+
+## Layout
+
+| Path | What goes there |
+| --- | --- |
+| `afterpresets.json` | Name, bundle ID, version (bumped by `ap push`), `"platform": "native"`, `"hosts": ["AEFT"]` |
+| `effect.json` | The effect: name, `matchName` (permanent), category, controls (permanent `id`s), license and update options, flags |
+| `src/Effect.cpp` | After Effects entry points: setup, parameters, Smart Render, Options |
+| `src/Render.h` | The pixel work (8/16/32 bits per channel) |
+| `src/License.cpp`, `src/License.h` | AfterPresets licensing, the Options dialog and the update notice |
+| `vendor/ap_native/` | AfterPresets native runtime; copied by `ap init` / `ap upgrade`. Do not edit |
+| `native.cmake` | Optional: extra libraries or compiler settings (CMake), included last |
+| `build/` | Build output and the generated `ap_effect_config.h` / `ap_effect_params.h`. Do not edit |
+| `test-fixtures/` | Sample footage or images for testing (never shipped) |
+
+## effect.json
+
+1. **Flags, names and versions come only from `effect.json`**, through the
+   generated `ap_effect_config.h`. Never type `PF_OutFlag_*` values by hand
+   in GlobalSetup, and never edit the generated headers.
+2. **Controls are declared in `effect.json`.** The generated
+   `ap_effect_params.h` adds them (`ap_add_params()`) and names their indices:
+   `params[AP_PARAM_AMOUNT]` for key `"amount"`; popup values are
+   `AP_<KEY>_<CHOICE>_<n>`.
+3. **Control `id`s (1-9000) are permanent.** Append new controls with new
+   ids; never reuse or renumber one. Saved projects find controls by id.
+   Id 9001 is the AfterPresets status button (`params[AP_PARAM_LICENSE]`,
+   always last): keep it.
+4. **The match name is permanent.** `ap init` made it unique for this
+   product, and After Effects saves it in every project that uses the
+   effect: changing it after the first release breaks every customer's
+   projects. The menu `name` can change any time.
+5. **Keep what makes it a good plugin** when you replace the starter: 8, 16
+   and 32 bits per channel, Smart Render, multi-frame rendering safety, and
+   the status button and Options dialog.
+6. **Keep the overview current.** When you add, move or remove controls or
+   files, update the Overview in `AGENTS.md`.
+
+## Licensing and updates
+
+Both are set in `effect.json`.
+
+- `"license": true` turns licensing on. Buyers sign in from the effect's
+  status button (caption "License...", or "About..." when licensing is off;
+  its name is the status line, e.g. "License: active") or from the Options
+  dialog. The effect renders unlocked only when `ap_is_unlocked()` says so
+  (safe on any thread). `{ "offlineGraceDays": 7 }` allows offline use
+  (0-30 days). Removing it turns licensing off: free products only. **Paid
+  products must license**: `ap check` and `ap push` fail otherwise.
+- Dev builds render **without** the watermark unless enforcement is on; see
+  "Testing the locked (signed-out) state" in `docs/afterpresets/testing.md`.
+  Release builds always enforce.
+- `"updates": "background"` (default) downloads and verifies a new version in
+  the background; it is used from the next After Effects start (the status
+  button says "Update: restart AE"). `"notify"` only tells the buyer,
+  `"manual"` checks when they ask in the Options dialog, `"off"` disables
+  updates. Explain the tradeoffs to the user before switching away from
+  `background`.
+
+## How buyers install it
+
+`ap build` puts `mac-install.command` and `windows-install.bat` in the
+release ZIP. Buyers run the one for their computer: the first install shows
+the system's administrator prompt once (macOS password window, Windows UAC)
+and copies the plugin into Adobe's shared plugin folder. macOS may first need
+**System Settings → Privacy & Security → Open Anyway** for the install
+script. Later updates install themselves and need only an After Effects
+restart. The user guide is at https://docs.afterpresets.com.

package/template/native/docs/initial_setup.md

@@ -0,0 +1,179 @@
+# Initial setup
+
+Do this once per computer. The user is usually not a programmer and may not
+have a terminal open (for example, they use the Code tab of the Claude
+desktop app). **Run every command yourself**; ask the user only for the
+steps marked **User**, one at a time, in plain words, and wait for "Done".
+Never ask them to type a command, and never use `sudo` yourself. If a
+command fails because your sandbox blocks the internet or writing to
+`~/.afterpresets`, ask the user to allow it to run outside the sandbox; do
+not work around it.
+
+Follow the steps for this computer's system (macOS or Windows). A Mac builds
+the macOS version and cross-compiles the Windows version; a Windows PC builds
+the Windows version only.
+
+## 1. Tools
+
+- [ ] `node --version` prints 20 or newer. If Node is missing: on Windows run
+  `winget install -e --id OpenJS.NodeJS.LTS`; on a Mac, **User** installs
+  the "LTS" version from https://nodejs.org (a normal installer). Then check
+  again (a new chat may be needed for the agent to see it).
+- [ ] `npm install` has run; `node_modules/afterpresets` exists.
+
+**macOS:**
+
+- [ ] Homebrew: `brew --version` works (also try `/opt/homebrew/bin/brew`
+  and `/usr/local/bin/brew`). If not, **User**: "Open https://brew.sh, copy
+  the install line into the Terminal app, press Return, and type your Mac
+  password when asked (nothing shows while you type). Press Return again
+  when it asks. If Apple's Command Line Tools are missing it downloads them
+  too (about 1 GB from Apple, 5-15 minutes); wait until it says
+  'Installation successful'." Then check again (Homebrew prints two lines to
+  add it to the PATH; follow them).
+- [ ] Apple's Command Line Tools (Apple's compiler and signing tools; Xcode
+  itself is not needed): `xcode-select -p` prints a folder. Homebrew's
+  installer normally installed them. If not, run `xcode-select --install`
+  and tell the **User**: "A macOS window asks to install the Command Line
+  Tools: click **Install** and wait until it finishes (about 5-15 minutes,
+  it downloads about 1 GB from Apple)."
+- [ ] Build tools: `brew install cmake ninja zig` (you run it). `cmake
+  --version`, `ninja --version` and `zig version` all work afterwards.
+
+**Windows** (Visual Studio is not needed):
+
+- [ ] Build tools, with winget (you run them; no administrator needed):
+  `winget install -e --id Kitware.CMake`, `winget install -e --id
+  Ninja-build.Ninja`, `winget install -e --id zig.zig`. `cmake --version`,
+  `ninja --version` and `zig version` all work afterwards (a new terminal,
+  or a new chat, may be needed to see them).
+
+**Both:**
+
+- [ ] The account: `whoami` (MCP) or `npx ap whoami`. If it says "not logged
+  in", call `login` (MCP) or run `npx ap login` in the background, then tell
+  the **User**: "Your browser opened an AfterPresets page; click **Authorize
+  CLI**." Wait with `login_status`, or until the command finishes.
+
+## 2. Adobe's After Effects SDK (one time per computer)
+
+Adobe does not allow AfterPresets to ship its SDK, and downloading it needs
+the user's Adobe ID, so this step is theirs.
+
+- [ ] Run `npx ap sdk`. If it says the SDK is installed, go on.
+- [ ] Otherwise run `npx ap sdk install`. It opens Adobe's download page. Tell
+  the **User**: "Sign in with your Adobe ID on the page that opened, and
+  download the **After Effects** SDK for **macOS** (or **Windows** on a PC; a
+  zip). Tell me when it
+  is in your Downloads folder." Never ask for their Adobe password.
+- [ ] Run `npx ap sdk install` again: it finds the zip in Downloads, checks
+  it and installs it into `~/.afterpresets/sdk/` (Windows:
+  `%USERPROFILE%\.afterpresets\sdk\`). If the zip is elsewhere,
+  pass its path: `npx ap sdk install <path to zip>`.
+
+## 3. AfterPresets MCP
+
+The `afterpresets` MCP server (`ap mcp`) gives you the CLI (login, check,
+dev, build, push), the docs, and After Effects itself (`host_eval`,
+`host_scratch_project`, `comp_capture`).
+
+- **Claude (desktop app Code tab, or Claude Code):** `.mcp.json` declares it.
+  If its tools are missing because this project was just created in this
+  chat (or in another folder), tell the **User** exactly how to start a new
+  chat in this folder, with its full path, and to approve the AfterPresets
+  tools when Claude asks:
+  - Claude app: "In the **Code** tab, start a new session, choose the
+    folder `<full path>`, and approve the AfterPresets tools when asked."
+  - Claude Code in a terminal: "Type `/exit`, then run
+    `cd "<full path>" && claude`, and approve the AfterPresets tools."
+  - Cursor or VS Code: "**File → Open Folder…**, choose `<full path>`,
+    open a new chat, and enable the afterpresets MCP server if asked."
+  Give them the message to paste into the new chat: "Continue the
+  AfterPresets setup: follow docs/initial_setup.md step by step until you
+  have shown me the starter effect rendering in After Effects, then ask me
+  what to build." Stop there; the
+  new chat continues from this file.
+- **Codex CLI** (run in this folder):
+
+  ```sh
+  codex mcp add afterpresets -- node node_modules/afterpresets/bin/ap.js mcp
+  ```
+
+  Then tell the **User**: "Quit Codex and start it again in this folder:
+  `cd "<full path>" && codex`."
+
+- **Other agents:** add a stdio server that runs
+  `node node_modules/afterpresets/bin/ap.js mcp` in this folder.
+
+- [ ] The `afterpresets` tools are visible to you.
+
+## 4. First build
+
+- [ ] Call `dev_start` (or `npx ap dev` if the user runs it). It builds the
+  effect, installs it into After Effects' dev plugin folder
+  (macOS: `/Library/Application Support/Adobe/Common/Plug-ins/7.0/MediaCore/AfterPresets Dev/`;
+  Windows: `C:\Program Files\Adobe\Common\Plug-ins\7.0\MediaCore\AfterPresets Dev\`),
+  installs the AfterPresets dev bridge (how the tools reach After Effects),
+  and converts Adobe's SDK guide into `docs/afterpresets/sdk/`. Then
+  `dev_status` until the build is done.
+- [ ] If it says the dev plugin folder needs an administrator, that is a
+  **User** step, needed once. **macOS:** it gives one Terminal line (`sudo mkdir -p …
+  && sudo chown …`). Tell the **User**: "Open the Terminal app, paste this
+  line, press Return and type your Mac password (nothing shows while you
+  type)." and give them the exact line it printed. (When `ap dev` runs in an
+  interactive terminal it may show the macOS administrator window instead:
+  then the **User** just enters their password there.) Never run `sudo`
+  yourself. **Windows:** it gives one PowerShell line (`New-Item … ;
+  icacls …`). Tell the **User**: "Right-click **Start**, choose **Terminal
+  (Admin)** or **Windows PowerShell (Admin)**, click **Yes**, paste this
+  line, press Enter, and tell me Done." and give them the exact line it
+  printed. Never elevate yourself. Then run `dev_start` / `dev_status`
+  again; later builds install without an administrator.
+- [ ] If it reports compiler errors on the untouched starter, the SDK or a
+  build tool is wrong: re-check steps 1 and 2 and read the hint it prints.
+- [ ] `docs/afterpresets/sdk/README.md` exists. If it says the guide could
+  not be downloaded, check the internet connection and run `npx ap docs`.
+
+## 5. Restart After Effects once
+
+- [ ] **User:** "Save your work in After Effects, then quit and reopen it."
+  (Needed now because After Effects loads plugins and the dev bridge only
+  when it starts. Later, on a Mac, `ap dev` restarts it for you when that
+  is safe, or tells you to ask; on Windows always ask the user.)
+- [ ] `host_bridge` (no action) says the bridge is loaded in After Effects.
+
+## 6. Prove the loop
+
+- [ ] A harmless host call works: `host_eval` with `app.version`.
+- [ ] The starter effect is loaded: in `host_eval`, look for the
+  `matchName` from `effect.json` in `app.effects` (see
+  `docs/afterpresets/debugging.md`).
+- [ ] `host_scratch_project`, then apply the starter effect to a solid in a
+  test comp with `host_eval` and capture two frames with `comp_capture`
+  (`docs/afterpresets/testing.md`). Look at them: the effect is visible.
+- [ ] Show the **User** the frames: "This is the starter effect, running in
+  After Effects. Next, tell me what yours should do."
+
+## 7. Ask what to build
+
+Only now, with the starter effect rendering, ask what the effect should do.
+Do not start building from a vague idea.
+
+- [ ] Ask the **User** to describe the look in detail, in their own words.
+  Invite references: images or video frames of the look they want, another
+  effect they like, or a frame from their own project. They can drag images
+  into the chat.
+- [ ] Ask short questions about anything unclear, a few at a time (for
+  example: which controls they want, what each one changes, how it should
+  animate, whether it works on the layer's edges or its whole image).
+- [ ] Repeat back a short plan in plain words (the look, the controls and
+  their ranges) and wait for their OK.
+- [ ] Write the Overview in `AGENTS.md` from the plan, following the
+  instructions there. Keep it current from now on.
+- [ ] Turn the starter into the product: its name, category, controls and
+  render code (`docs/code_guide.md` lists what to keep). Build it in small
+  steps, rendering and showing frames after each one.
+
+Repeat after moving the project, installing a new After Effects version, or
+switching agents (skip step 7 when the Overview in `AGENTS.md` is already
+written).

package/template/native/docs/release_checklist.md

@@ -0,0 +1,24 @@
+# Before the first production release
+
+Do this once, before the first `push` to `production`. Tell the user what you
+are doing; show them the frames and wait for their feedback.
+
+- [ ] **Licensing matches the price.** A paid product keeps
+  `"license": true` in `effect.json` (`ap check` and `ap push` refuse
+  otherwise). A free one may remove it. See `docs/code_guide.md`.
+- [ ] **The locked state works.** Turn enforcement on as described in
+  "Testing the locked (signed-out) state" in `docs/afterpresets/testing.md`,
+  restart After Effects, and render frames signed out: the effect must still
+  render (with the watermark), never crash or hang. Render frames signed in
+  too. Then turn enforcement off again.
+- [ ] **Show the user** the locked and unlocked frames and ask for feedback.
+- [ ] **The match name and control ids are final.** After this release they
+  can never change (see `docs/code_guide.md`). Confirm the effect's name and
+  controls with the user.
+- [ ] **A test release works.** `push` to `test` and let the user try it.
+  Built on a Mac, the release also has the Windows version: tell the user to
+  test it on a Windows PC before selling it there.
+- [ ] `check` passes with no errors.
+
+Then `push` to `production`: show the user the summary it returns, and call
+it again with its `confirmToken` only after they approve.

package/template/native/effect.json

@@ -0,0 +1,16 @@
+{
+  "name": "__EFFECT_NAME__",
+  "matchName": "__MATCH_NAME__",
+  "category": "AfterPresets",
+  "description": "Tints the layer toward a colour.",
+  "license": true,
+  "updates": "background",
+  "params": [
+    { "key": "amount", "id": 1, "type": "slider", "name": "Amount", "min": 0, "max": 100, "default": 50, "precision": 1, "display": "percent" },
+    { "key": "color", "id": 2, "type": "color", "name": "Color", "default": "#FF4000" },
+    { "key": "mode", "id": 3, "type": "popup", "name": "Mode", "choices": ["Tint", "Screen", "Multiply"], "default": "Tint" },
+    { "key": "gradient", "id": 4, "type": "checkbox", "name": "Gradient", "label": "Fade across layer", "default": false },
+    { "key": "center", "id": 5, "type": "point", "name": "Gradient Center", "default": [50, 50] },
+    { "key": "angle", "id": 6, "type": "angle", "name": "Gradient Angle", "default": 90 }
+  ]
+}

package/template/native/gitignore

@@ -0,0 +1,8 @@
+# Build output (ap build / ap dev)
+/build/
+/dist/
+
+# Never commit Adobe's SDK (it lives in ~/.afterpresets/sdk/)
+AfterEffectsSDK*/
+
+.DS_Store

package/template/native/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "__SLUG__",
+  "private": true,
+  "scripts": {
+    "dev": "ap dev",
+    "check": "ap check",
+    "build": "ap build",
+    "push": "ap push",
+    "docs": "ap docs"
+  },
+  "devDependencies": {
+    "afterpresets": "^__CLI_VERSION__"
+  }
+}

package/template/native/src/Effect.cpp

@@ -0,0 +1,224 @@
+// The starter effect: tints the layer toward a colour (Tint, Screen or
+// Multiply), optionally fading across the layer along a gradient.
+//
+// Plain After Effects SDK code. Names, flags, version and parameters come from
+// effect.json through the generated ap_effect_config.h / ap_effect_params.h:
+// change effect.json, not the numbers here.
+//
+//   8/16/32 bpc        DEEP_COLOR_AWARE + FLOAT_COLOR_AWARE, one template (Render.h)
+//   Smart Render       PF_Cmd_SMART_PRE_RENDER / PF_Cmd_SMART_RENDER
+//   Multi-frame render no mutable globals; everything a render needs is on the stack
+//   AfterPresets       status button + Options dialog (License.cpp, ap_native)
+#include "AEConfig.h"
+#include "entry.h"
+#include "AE_Effect.h"
+#include "AE_EffectVers.h"
+#include "AE_EffectCB.h"
+#include "AE_EffectCBSuites.h"
+#include "AE_EffectSuites.h"
+#include "AE_Macros.h"
+#include "Param_Utils.h"
+
+#include <cmath>
+#include <cstdio>
+#include <cstring>
+#include <new>
+
+#include "ap_effect_params.h" // generated from effect.json
+#include "License.h"
+#include "Render.h"
+
+namespace {
+
+// Decided once per frame in PreRender and handed to SmartRender.
+struct PreRenderData {
+  A_long left, top; // where the output buffer sits in layer space (downsampled pixels)
+  A_long unlocked;  // license state for this frame (also mixed into the cache key)
+};
+
+void delete_pre_render_data(void *data) { delete static_cast<PreRenderData *>(data); }
+
+PF_Err about(PF_OutData *out_data) {
+  std::snprintf(out_data->return_msg, sizeof out_data->return_msg, "%s %s\r%s", AP_EFFECT_NAME, AP_VERSION,
+                AP_DESCRIPTION);
+  return PF_Err_NONE;
+}
+
+PF_Err global_setup(PF_OutData *out_data) {
+  out_data->my_version = AP_EFFECT_VERSION; // equals the PiPL's eVER (both from afterpresets.json)
+  out_data->out_flags = AP_OUT_FLAGS;       // equals the PiPL's eGLO (both from effect.json)
+  out_data->out_flags2 = AP_OUT_FLAGS2;     // equals the PiPL's eGL2
+  license::start();
+  return PF_Err_NONE;
+}
+
+PF_Err params_setup(PF_InData *in_data, PF_OutData *out_data) {
+  char status[32];
+  license::status_name(status, sizeof status);
+  return ap_add_params(in_data, out_data, status, license::button_label());
+}
+
+// The status button's name shows the license / update state. Names are the
+// only text an effect can change in the Effect Controls without custom UI.
+PF_Err update_params_ui(PF_InData *in_data, PF_ParamDef *params[]) {
+  PF_ParamDef def = *params[AP_PARAM_LICENSE];
+  char status[32];
+  license::status_name(status, sizeof status);
+  if (std::strncmp(def.PF_DEF_NAME, status, sizeof def.PF_DEF_NAME) == 0) return PF_Err_NONE;
+  std::snprintf(def.PF_DEF_NAME, sizeof def.PF_DEF_NAME, "%s", status);
+  const PF_ParamUtilsSuite3 *pu = nullptr;
+  PF_Err err = PF_Err_NONE;
+  if (in_data->pica_basicP->AcquireSuite(kPFParamUtilsSuite, kPFParamUtilsSuiteVersion3, (const void **)&pu) == 0 && pu) {
+    err = pu->PF_UpdateParamUI(in_data->effect_ref, AP_PARAM_LICENSE, &def);
+    in_data->pica_basicP->ReleaseSuite(kPFParamUtilsSuite, kPFParamUtilsSuiteVersion3);
+  }
+  return err;
+}
+
+// Effect > Options or the status button: the AfterPresets dialog (sign in,
+// buy, sign out, update notes). Re-render: signing in or out changes the frame.
+PF_Err show_options(PF_OutData *out_data) {
+  license::options_dialog();
+  out_data->out_flags |= PF_OutFlag_FORCE_RERENDER;
+  return PF_Err_NONE;
+}
+
+PF_Err user_changed_param(PF_OutData *out_data, const PF_UserChangedParamExtra *extra) {
+  if (extra->param_index == AP_PARAM_LICENSE) return show_options(out_data);
+  return PF_Err_NONE;
+}
+
+PF_Err pre_render(PF_InData *in_data, PF_PreRenderExtra *extra) {
+  PF_RenderRequest req = extra->input->output_request;
+  PF_CheckoutResult in_result;
+  PF_Err err = extra->cb->checkout_layer(in_data->effect_ref, AP_PARAM_INPUT, AP_PARAM_INPUT, &req,
+                                         in_data->current_time, in_data->time_step, in_data->time_scale, &in_result);
+  if (err) return err;
+  // Pixel-independent: the output covers exactly what the input provides.
+  extra->output->result_rect = in_result.result_rect;
+  extra->output->max_result_rect = in_result.max_result_rect;
+  // The license state is part of the frame: mix it into After Effects' cache key
+  // (with PF_OutFlag2_I_MIX_GUID_DEPENDENCIES) so a frame rendered locked is
+  // never shown after sign-in, and the reverse.
+  A_long unlocked = license::unlocked() ? 1 : 0;
+  err = extra->cb->GuidMixInPtr(in_data->effect_ref, sizeof unlocked, &unlocked);
+  if (err) return err;
+  PreRenderData *data = new (std::nothrow) PreRenderData{in_result.result_rect.left, in_result.result_rect.top, unlocked};
+  if (!data) return PF_Err_OUT_OF_MEMORY;
+  extra->output->pre_render_data = data;
+  extra->output->delete_pre_render_data_func = delete_pre_render_data;
+  return PF_Err_NONE;
+}
+
+PF_Err smart_render(PF_InData *in_data, PF_SmartRenderExtra *extra) {
+  PF_Err err = PF_Err_NONE;
+  PF_EffectWorld *input = nullptr, *output = nullptr;
+  err = extra->cb->checkout_layer_pixels(in_data->effect_ref, AP_PARAM_INPUT, &input);
+  if (!err) err = extra->cb->checkout_output(in_data->effect_ref, &output);
+
+  // Check out every parameter at the current time (checked back in below).
+  const int ids[] = {AP_PARAM_AMOUNT, AP_PARAM_COLOR, AP_PARAM_MODE, AP_PARAM_GRADIENT, AP_PARAM_CENTER, AP_PARAM_ANGLE};
+  const int n = (int)(sizeof ids / sizeof ids[0]);
+  PF_ParamDef p[sizeof ids / sizeof ids[0]];
+  bool checked[sizeof ids / sizeof ids[0]] = {};
+  for (int i = 0; i < n && !err; ++i) {
+    AEFX_CLR_STRUCT(p[i]);
+    err = PF_CHECKOUT_PARAM(in_data, ids[i], in_data->current_time, in_data->time_step, in_data->time_scale, &p[i]);
+    checked[i] = !err;
+  }
+
+  if (!err && input && output) {
+    const PreRenderData *pre = static_cast<const PreRenderData *>(extra->input->pre_render_data);
+    TintParams tp;
+    tp.amount = (float)(p[0].u.fs_d.value / 100.0);
+    tp.r = p[1].u.cd.value.red / 255.f;
+    tp.g = p[1].u.cd.value.green / 255.f;
+    tp.b = p[1].u.cd.value.blue / 255.f;
+    tp.mode = p[2].u.pd.value;
+    tp.gradient = p[3].u.bd.value != 0;
+    // Point values arrive in layer pixels at the current resolution (16.16
+    // fixed; After Effects already applied the downsample factor; verified at
+    // half resolution). The buffers start at the pre-render rectangle's corner.
+    tp.cx = (float)p[4].u.td.x_value / 65536.f - (pre ? pre->left : 0);
+    tp.cy = (float)p[4].u.td.y_value / 65536.f - (pre ? pre->top : 0);
+    const float rad = (float)p[5].u.ad.value / 65536.f * 3.14159265f / 180.f; // 0 degrees points up
+    tp.dirx = std::sin(rad);
+    tp.diry = -std::cos(rad);
+    tp.span = (float)(input->width > input->height ? input->width : input->height);
+    if (tp.span < 1.f) tp.span = 1.f;
+    tp.watermark = pre ? !pre->unlocked : !license::unlocked();
+
+    PF_PixelFormat fmt = PF_PixelFormat_ARGB32;
+    const PF_WorldSuite2 *ws = nullptr;
+    if (in_data->pica_basicP->AcquireSuite(kPFWorldSuite, kPFWorldSuiteVersion2, (const void **)&ws) == 0 && ws) {
+      err = ws->PF_GetPixelFormat(output, &fmt);
+      in_data->pica_basicP->ReleaseSuite(kPFWorldSuite, kPFWorldSuiteVersion2);
+    }
+    const int w = output->width < input->width ? output->width : input->width;
+    const int h = output->height < input->height ? output->height : input->height;
+    const char *src = (const char *)input->data;
+    char *dst = (char *)output->data;
+    if (!err) {
+      switch (fmt) {
+      case PF_PixelFormat_ARGB128:
+        tint_rows<PF_PixelFloat, 1, true>(src, input->rowbytes, dst, output->rowbytes, w, h, tp);
+        break;
+      case PF_PixelFormat_ARGB64:
+        tint_rows<PF_Pixel16, PF_MAX_CHAN16, false>(src, input->rowbytes, dst, output->rowbytes, w, h, tp);
+        break;
+      case PF_PixelFormat_ARGB32:
+        tint_rows<PF_Pixel8, PF_MAX_CHAN8, false>(src, input->rowbytes, dst, output->rowbytes, w, h, tp);
+        break;
+      default:
+        err = PF_Err_BAD_CALLBACK_PARAM;
+      }
+    }
+  }
+
+  for (int i = 0; i < n; ++i) {
+    if (checked[i]) {
+      PF_Err e2 = PF_CHECKIN_PARAM(in_data, &p[i]);
+      if (!err) err = e2;
+    }
+  }
+  if (input) {
+    PF_Err e2 = extra->cb->checkin_layer_pixels(in_data->effect_ref, AP_PARAM_INPUT);
+    if (!err) err = e2;
+  }
+  return err;
+}
+
+} // namespace
+
+extern "C" DllExport PF_Err PluginDataEntryFunction2(PF_PluginDataPtr inPtr, PF_PluginDataCB2 inPluginDataCallBackPtr,
+                                                     SPBasicSuite *, const char *, const char *) {
+  PF_Err result = PF_Err_INVALID_CALLBACK;
+  result = PF_REGISTER_EFFECT_EXT2(inPtr, inPluginDataCallBackPtr, AP_EFFECT_NAME, AP_MATCH_NAME, AP_CATEGORY,
+                                   AE_RESERVED_INFO, "EffectMain", AP_SUPPORT_URL);
+  return result;
+}
+
+extern "C" DllExport PF_Err EffectMain(PF_Cmd cmd, PF_InData *in_data, PF_OutData *out_data, PF_ParamDef *params[],
+                                       PF_LayerDef *output, void *extra) {
+  (void)output;
+  PF_Err err = PF_Err_NONE;
+  try {
+    switch (cmd) {
+    case PF_Cmd_ABOUT: err = about(out_data); break;
+    case PF_Cmd_GLOBAL_SETUP: err = global_setup(out_data); break;
+    case PF_Cmd_GLOBAL_SETDOWN: license::stop(); break;
+    case PF_Cmd_PARAMS_SETUP: err = params_setup(in_data, out_data); break;
+    case PF_Cmd_UPDATE_PARAMS_UI: err = update_params_ui(in_data, params); break;
+    case PF_Cmd_USER_CHANGED_PARAM:
+      err = user_changed_param(out_data, static_cast<const PF_UserChangedParamExtra *>(extra));
+      break;
+    case PF_Cmd_DO_DIALOG: err = show_options(out_data); break;
+    case PF_Cmd_SMART_PRE_RENDER: err = pre_render(in_data, static_cast<PF_PreRenderExtra *>(extra)); break;
+    case PF_Cmd_SMART_RENDER: err = smart_render(in_data, static_cast<PF_SmartRenderExtra *>(extra)); break;
+    default: break;
+    }
+  } catch (...) {
+    err = PF_Err_INTERNAL_STRUCT_DAMAGED; // never let a C++ exception reach After Effects
+  }
+  return err;
+}