├── docs ├── _static │ ├── extra.css │ └── env-vars.png ├── _global │ ├── js │ │ └── global.js │ ├── .gitignore │ ├── requirements.txt │ ├── css │ │ ├── global.css │ │ └── global-syntax-highlight.css │ ├── overrides │ │ ├── 404.html │ │ ├── main.html │ │ ├── partials │ │ │ ├── toc-item.html │ │ │ └── copyright.html │ │ └── templates │ │ │ ├── print_site_banner.tpl │ │ │ └── print_site_cover_page.tpl │ ├── readme.md │ ├── scripts │ │ └── update-common-components.py │ ├── hooks │ │ ├── inline_pre_to_code_fence.py │ │ └── merge_inherited_config.py │ └── mkdocs.yml ├── CNAME ├── hardware │ ├── hardware.md │ ├── classid-filetype-subtype.md │ ├── hardware-integration-components.md │ └── classdata-functions.md ├── gpu-effects-transitions │ ├── return-codes.md │ ├── whats-new-in-ppro-cc2014.md │ ├── whats-new-in-ppro-cc2015.md │ ├── cuda-opencl-metal-opengl.md │ ├── whats-new-in-ppro-12.md │ ├── PrGPUFilter-function-table.md │ ├── function-descriptions.md │ ├── suites.md │ ├── gpu-effects-transitions.md │ ├── getting-started.md │ ├── PrGPU-SDK-macros.md │ └── structure-descriptions.md ├── resources │ ├── resources.md │ ├── impt-resource.md │ └── pipl-resource.md ├── intro │ ├── what-premiere-plugins-do.md │ ├── best-practices.md │ ├── sdk-audience.md │ ├── getting-support.md │ ├── where-do-i-start.md │ ├── document-overview.md │ ├── localization.md │ ├── debugging-plugins.md │ ├── load-em-up.md │ ├── sample-projects.md │ ├── premiere-pro-plugin-types.md │ └── plugin-installation.md ├── universals │ ├── universals.md │ ├── fields.md │ ├── pixel-aspect-ratio.md │ ├── suites.md │ ├── video-frames.md │ ├── time.md │ ├── memory-management.md │ └── audio.md ├── importers │ ├── suites.md │ ├── importers.md │ ├── return-codes.md │ └── whats-new.md ├── ae-transition-extensions │ ├── PF_TransitionSuite.md │ ├── ae-transition-extensions.md │ └── getting-started.md ├── index.md ├── exporters │ ├── exporters.md │ ├── structures.md │ ├── additional-details.md │ ├── selector-table.md │ ├── whats-new.md │ ├── selector-descriptions.md │ └── return-codes.md ├── video-filters │ ├── video-filters.md │ ├── return-codes.md │ ├── whats-new.md │ ├── selector-table.md │ ├── additional-details.md │ ├── getting-started.md │ └── selector-descriptions.md ├── export-controllers │ └── export-controllers.md ├── control-surfaces │ └── control-surfaces.md ├── transmitters │ ├── transmitters.md │ ├── suites.md │ └── transmitter-basics.md └── history.md ├── requirements.txt ├── .gitignore ├── .gitattributes ├── readme.md ├── .github └── workflows │ └── ci.yml └── mkdocs.yml /docs/_static/extra.css: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/_global/js/global.js: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/CNAME: -------------------------------------------------------------------------------- 1 | ppro-plugins.docsforadobe.dev 2 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | -r docs/_global/requirements.txt 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.sublime-project 2 | *.sublime-workspace 3 | .DS_Store 4 | .vscode/ 5 | __pycache__/ 6 | site/ 7 | venv/ 8 | -------------------------------------------------------------------------------- /docs/_static/env-vars.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/docsforadobe/premiere-plugin-guide/HEAD/docs/_static/env-vars.png -------------------------------------------------------------------------------- /.gitattributes: -------------------------------------------------------------------------------- 1 | # Override linguist skipping main folder 2 | docs/** -linguist-documentation 3 | docs/** linguist-detectable 4 | -------------------------------------------------------------------------------- /docs/_global/.gitignore: -------------------------------------------------------------------------------- 1 | *.sublime-project 2 | *.sublime-workspace 3 | .DS_Store 4 | .vscode/ 5 | __pycache__/ 6 | site/ 7 | venv/ 8 | -------------------------------------------------------------------------------- /docs/_global/requirements.txt: -------------------------------------------------------------------------------- 1 | markdown_grid_tables 2 | mkdocs 3 | mkdocs-git-revision-date-localized-plugin 4 | mkdocs-material 5 | mkdocs-print-site-plugin 6 | -------------------------------------------------------------------------------- /docs/hardware/hardware.md: -------------------------------------------------------------------------------- 1 | # Hardware 2 | 3 | To integrate hardware with Premiere Pro, you may consider three types of plugins: 4 | 5 | - importers, 6 | - exporters, 7 | - transmitters 8 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/return-codes.md: -------------------------------------------------------------------------------- 1 | # Return Codes 2 | 3 | | Return Code | Reason | 4 | | ----------------- | --------- | 5 | | `malNoError` | No error. | 6 | | `malUnknownError` | Error. | 7 | -------------------------------------------------------------------------------- /docs/resources/resources.md: -------------------------------------------------------------------------------- 1 | # Resources 2 | 3 | There are two types of special resources that are specific to Premiere plugins: the PiPL and the IMPT. 4 | 5 | This chapter describes these resources, and how certain plugin types use them. 6 | -------------------------------------------------------------------------------- /docs/_global/css/global.css: -------------------------------------------------------------------------------- 1 | /* 2 | Fix issue with 'code' text in tables wrapping to multiple lines 3 | Excludes any preformatted code blocks within tables 4 | */ 5 | td code:not(.md-code__content) { 6 | white-space: nowrap; 7 | } 8 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/whats-new-in-ppro-cc2014.md: -------------------------------------------------------------------------------- 1 | # What's New in Premiere Pro CC 2014? 2 | 3 | OpenCL rendering now also uses the half-precision 16-bit floating point pixel format for rendering. GPU-accelerated effects and transitions should implement both 16f and 32f rendering. 4 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/whats-new-in-ppro-cc2015.md: -------------------------------------------------------------------------------- 1 | # What's New in Premiere Pro CC 2015.4? 2 | 3 | GPU-accelerated rendering using Metal is now supported for third-party effects and transitions. `PrGPUDeviceFramework_Metal` has been added as one of the enum values in `PrGPUDeviceFramework`. 4 | -------------------------------------------------------------------------------- /docs/intro/what-premiere-plugins-do.md: -------------------------------------------------------------------------------- 1 | # What Premiere plugins Do 2 | 3 | Premiere APIs provide access to many points of the video editing pipeline. 4 | 5 | Media import and export, video effects and transitions, and sending video and audio to external hardware can all be performed by plugins. 6 | -------------------------------------------------------------------------------- /docs/universals/universals.md: -------------------------------------------------------------------------------- 1 | # Universals 2 | 3 | This chapter covers topics that are common to more than one type of Premiere plugin. We start by discussing fundamental concepts and common data structures. The rest of the chapter discusses the various function suites that are available to plugins. 4 | -------------------------------------------------------------------------------- /docs/universals/fields.md: -------------------------------------------------------------------------------- 1 | # Fields 2 | 3 | There are different constants defined for fields. These constants are now largely interchangable in CS4, since the conflicting constants for the old compiler API have been removed. 4 | 5 | `prFieldsNone` 6 | 7 | `prFieldsUpperFirst` 8 | 9 | `prFieldsLowerFirst` 10 | 11 | `prFieldsUnknown` 12 | 13 | `prFieldsAny` 14 | 15 | `prFieldsInvalid` 16 | -------------------------------------------------------------------------------- /docs/universals/pixel-aspect-ratio.md: -------------------------------------------------------------------------------- 1 | # Pixel Aspect Ratio 2 | 3 | Pixel Aspect Ratio (PAR) is represented as a rational number, with a numerator and a denominator. 4 | 5 | Here are some examples of pixel aspect ratios: 6 | 7 | - NTSC DV 0.9091 PAR is (10, 11) 8 | - NTSC DV Widescreen 1.2121 PAR is (40, 33) 9 | - PAL DV 1.0940 PAR is (768, 702) 10 | - PAL DV 1.4587 PAR is (1024, 702) 11 | - Square 1.0 PAR is (1,1) 12 | -------------------------------------------------------------------------------- /docs/_global/overrides/404.html: -------------------------------------------------------------------------------- 1 | {% extends "main.html" %} 2 | 3 | 4 | {% block extrahead %} 5 | 10 | {% endblock %} 11 | 12 | {% block content %} 13 |

404 - Not found

14 | {% endblock %} 15 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/cuda-opencl-metal-opengl.md: -------------------------------------------------------------------------------- 1 | # CUDA, OpenCL, Metal, or OpenGL? 2 | 3 | As of Summer 2021, Premiere Pro no longer supports OpenCL. The GPU architecture of Premiere Pro is entirely CUDA/Metal, and this is what is exposed through the GPU extensions to the effect/transition APIs. 4 | 5 | Premiere Pro plugins have the ability to transfer frames from CUDA to OpenGL (though not always efficiently). Read more about that here. 6 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/whats-new-in-ppro-12.md: -------------------------------------------------------------------------------- 1 | # What's New in Premiere Pro 12.0? 2 | 3 | GPU effects and transitions built using this SDK can now be compatible with After Effects 15.0 and later. The sample GPU effect projects have been updated so that they load in both Premiere Pro and After Effects. 4 | 5 | The newly provided PrGPU SDK macros and device functions allow you to write kernels that will compile on multiple GPU compute languages - OpenCL, CUDA, and Metal. 6 | -------------------------------------------------------------------------------- /docs/_global/overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | {% block announce %} 4 | Welcome to the new docsforadobe guide! 5 | 6 | This is a work in progress. 7 | 8 | Please provide all feedback via 9 | 10 | 11 | {% include ".icons/octicons/comment-discussion-16.svg" %} 12 | 13 | the org's discussion forum 14 | . 15 | {% endblock %} 16 | -------------------------------------------------------------------------------- /docs/importers/suites.md: -------------------------------------------------------------------------------- 1 | # Suites 2 | 3 | For information on how to acquire and manage suites, see [SweetPea Suites](../universals/sweetpea-suites.md). 4 | 5 | ## Async File Reader Suite 6 | 7 | New in Premiere Pro CS5. A cross-platform file handling suite. 8 | 9 | ## Deferred Processing Suite 10 | 11 | Allows an importer to schedule processing time when importing asynchronously, and to notify the user that the media item is pending additional processing. 12 | 13 | In the Project panel, the name of the item will be italicized, and its thumbnail will show as Pending. 14 | -------------------------------------------------------------------------------- /docs/ae-transition-extensions/PF_TransitionSuite.md: -------------------------------------------------------------------------------- 1 | # PF_TransitionSuite 2 | 3 | In PrSDKAESupport.h, we've added `PF_TransitionSuite::RegisterTransitionInputParam()`. 4 | 5 | This call must be made before the `PF_ADD_PARAM()` call during `PF_Cmd_PARAM_SETUP`. 6 | 7 | Pass in the param to be used as the input layer for the other side of the transition. 8 | 9 | This enables your effect to be applied between two clips in the timeline just like our native transitions, but it will show up in the Effect Controls panel with full keyframable parameters similar to existing AE effects. 10 | -------------------------------------------------------------------------------- /docs/intro/best-practices.md: -------------------------------------------------------------------------------- 1 | # Best Practices 2 | 3 | When a plugin receives a selector it doesn't recognize, it should always return the code specific to the plugin type that means the selector is not supported (i.e. imUnsupported, rmUnsupported, etc). 4 | 5 | In this way, new selectors can be added to the API and legacy plugins will automatically answer whether or not they support it. 6 | 7 | --- 8 | 9 | ## Structure Alignment 10 | 11 | All the sample projects include `PrSDKTypes.h`. 12 | 13 | This header sets the proper (single-byte) structure alignment and specifies the necessary (C-style) external linkage. 14 | -------------------------------------------------------------------------------- /docs/_global/overrides/partials/toc-item.html: -------------------------------------------------------------------------------- 1 |
  • 2 | 3 | 4 | {{ toc_item.title }} 5 | 6 | 7 | 8 | 9 | {% if toc_item.children %} 10 | 19 | {% endif %} 20 |
    • 21 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | # Premiere C++ Plugin SDK Guide 2 | 3 | This repo hosts the Premiere C++ Plugin SDK Guide community docs. 4 | 5 | --- 6 | 7 | ## Contributing 8 | 9 | This endeavour is primarily community-supported and run; contributors are welcome and encouraged to suggest fixes, adjustments, notes/warnings, and anything else that may help the project. 10 | 11 | For specific information on how to contribute & best practices, see the [Documentation Contribution Guide](https://docsforadobe.dev/contributing/contribution-guide/). 12 | 13 | --- 14 | 15 | ## Licensing & Ownership 16 | 17 | This project exists for educational purposes only. 18 | 19 | All content is copyright Adobe Systems Incorporated. 20 | -------------------------------------------------------------------------------- /docs/ae-transition-extensions/ae-transition-extensions.md: -------------------------------------------------------------------------------- 1 | # AE Transition Extensions 2 | 3 | This chapter describes how to build native transitions in Premiere Pro based on the After Effects API. From a user's perspective, plugins built this way can show their parameters directly in the Effect Controls panel, even providing custom parameter UI in that panel or in the Sequence Monitor. Such plugins can run not only in Premiere Pro, but also in After Effects, although they will appear as effects rather than transitions. 4 | 5 | The transition extensions work on top of effects built using the After Effects SDK. Since AE effects only have a single input, the second input is a layer parameter defined by the plugin. 6 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | Welcome to the Adobe® Premiere® Pro Software Development Kit! 4 | 5 | This is a living document, and is constantly being updated and edited. The latest release of the SDK is available at: [https://www.adobe.io/apis/creativecloud/premierepro.html](http://www.adobe.io/apis/creativecloud/premierepro.html). 6 | 7 | If you have questions about the APIs described in this document, or about integration with Premiere Pro, your question may already be answered on the Premiere Pro SDK forum at: [https://community.adobe.com/t5/forums/filteredbylabelpage/board-id/premiere-pro/label-name/sdk](https://community.adobe.com/t5/forums/filteredbylabelpage/board-id/premiere-pro/label-name/sdk). 8 | -------------------------------------------------------------------------------- /docs/exporters/exporters.md: -------------------------------------------------------------------------------- 1 | # Exporters 2 | 3 | Exporters are used to export video, audio, and markers in any format. Exporters get individual video frames in a requested pixel format (generally, uncompressed video) and uncompressed audio. The exporter is responsible for any compression of the video and audio data, and wrapping the output in a file format. 4 | 5 | Exporters can be used from within Premiere Pro or Adobe Media Encoder. From within Premiere Pro, they are accessed via File > Export > Media. From there, the Export Settings dialog appears. The format chosen in the Format drop-down determines the exporter used, and the exporter provides the parameter settings and summary displayed in the Export Settings dialog. 6 | -------------------------------------------------------------------------------- /docs/resources/impt-resource.md: -------------------------------------------------------------------------------- 1 | # IMPT Resource 2 | 3 | Premiere Pro looks for an IMPT resource to identify a plugin as an importer. 4 | 5 | Before Premiere Pro 1.0, the IMPT resource was also used to declare the file extension supported by an importer. Since file extensions are now declared during imGetIndFormat, the drawtype four character code in the IMPT resource is no longer used by Premiere Pro. 6 | 7 | However, a unique drawtype fourcc is needed for the importer to function properly in After Effects on macOS. 8 | 9 | Do not use 0x4D4F6F76. This is already reserved by After Effects. 10 | 11 | ```cpp 12 | 1000 IMPT DISCARDABLE BEGIN 13 | 0x12345678 // Put your own unique hexadecimal code here 14 | END 15 | ``` 16 | -------------------------------------------------------------------------------- /docs/intro/sdk-audience.md: -------------------------------------------------------------------------------- 1 | # SDK Audience 2 | 3 | The Premiere Pro Software Development Kit enables developers to create plugins for Premiere Pro, After Effects, Audition, Media Encoder, Character Animator, and Premiere Elements. 4 | 5 | The required development environment for Windows is Microsoft Visual Studio 2022 LTSC 17.12. 6 | 7 | On macOS, the minimum environment is XCode 16.2 on macOS 15.7.1 or later. 8 | 9 | The SDK includes sample projects for these development environments. While the APIs in use are C compatible, the sample code is written in C++. Other compilers, build configurations, and programming languages are all 100% NOT supported. 10 | 11 | If this is your first time developing a Premiere Pro plugin, you can skip [Whats New](whats-new.md). 12 | -------------------------------------------------------------------------------- /docs/universals/suites.md: -------------------------------------------------------------------------------- 1 | # Suites 2 | 3 | There are different sets of function suites available to Premiere plugins. [SweetPea Suites](sweetpea-suites.md) are the more modern suites that have been added for most new functionality. The [piSuites](legacy-callback-suites.md#pisuites) are still needed for various functionality that has not all been superceded by [SweetPea Suites](sweetpea-suites.md). 4 | 5 | Whenever possible, use [SweetPea Suites](sweetpea-suites.md). 6 | 7 | There are also function suites more specific to certain plugin types. The [Bottleneck Functions](legacy-callback-suites.md#bottleneck-functions) are useful for transitions and video filters. Other suites available to only one plugin type are documented in the appropriate chapter for that plugin type. 8 | -------------------------------------------------------------------------------- /docs/_global/readme.md: -------------------------------------------------------------------------------- 1 | # docsforadobe.dev MkDocs Config 2 | 3 | This repo holds the common components shared between this org's hosted MkDocs documentation projects. 4 | 5 | The idea is that this repo will be kept up-to-date with global config, and each child repo will use the provided script to download the latest commit from this repo, and have its "local" MkDocs config point to the downloaded files from this repo. 6 | 7 | In all cases, each child repo will be able to *override* config items here as needed. 8 | 9 | ## Updating This Repo 10 | 11 | See [Modifying Common Components](https://docsforadobe.dev/contributing/common-components/modifying-common-components/) in the org contribution guide for info on how this repo works, and best practices for modifying it. 12 | -------------------------------------------------------------------------------- /docs/_global/overrides/partials/copyright.html: -------------------------------------------------------------------------------- 1 |
    2 | {% if config.copyright %} 3 |
    4 | {{ config.copyright }} 5 |
    6 | {% endif %} 7 | {% if not config.extra.generator == false %} 8 | Made with 9 | 13 | Material for MkDocs 14 | 15 | {% endif %} 16 |
    17 | 18 | 19 |
    20 | {% if page.url_to_print_page %} 21 | 22 | {% include ".icons/material/printer.svg" %} 23 | 24 | {% endif %} 25 |
    26 | -------------------------------------------------------------------------------- /docs/_global/overrides/templates/print_site_banner.tpl: -------------------------------------------------------------------------------- 1 | 6 | 7 |
    8 | 9 |

    Note – This box will disappear during export!

    10 | 11 |

    This page has combined all site pages into one, and can be exported using native browser features.

    12 | 13 |

    You can export to PDF using File > Print > Save as PDF, or save as a single-page HTML file via File > Save As.

    14 | 15 |
    16 |

    Warning

    17 | 18 |

    Note that users may have issues printing to PDF on Firefox.

    19 |
    20 | 21 |
    22 | -------------------------------------------------------------------------------- /docs/video-filters/video-filters.md: -------------------------------------------------------------------------------- 1 | # Video Filters 2 | 3 | We strongly recommend using the **After Effects SDK** to develop effects plugins. 4 | 5 | Almost all of the effects included in Premiere Pro are After Effects plugins, and future development will be based on the After Effects API. 6 | 7 | Video filters process a video frame into a destination frame. Filter parameters can vary with time. 8 | 9 | Premiere provides basic user interface in the Effect Controls panel, drawing sliders, color pickers, angle dials, and checkboxes based on the parameter definitions in the PiPL resource. Video filters can have their own custom modal setup dialog for additional settings. 10 | 11 | If you've never developed a video filter before, you can skip [Whats New](whats-new.md), and go directly to [Getting Started](getting-started.md). 12 | -------------------------------------------------------------------------------- /docs/video-filters/return-codes.md: -------------------------------------------------------------------------------- 1 | # Return Codes 2 | 3 | | Return Code | Reason | 4 | | -------------------- | ------------------------------------------------------------------------------------- | 5 | | `fsNoErr` | Operation has completed without error. | 6 | | `fsBadFormatIndex` | Return from `fsGetPixelFormatsSupported` when all pixel formats have been enumerated. | 7 | | `fsDoNotCacheOnLoad` | Return from `fsCacheOnLoad` to disable plugin caching for this filter. | 8 | | `fsHasNoSetupDialog` | Return from `fsHasSetupDialog` to disable setup button in Effect Controls panel | 9 | | `fsUnsupported` | The selector is not recognized, or unsupported. | 10 | -------------------------------------------------------------------------------- /docs/video-filters/whats-new.md: -------------------------------------------------------------------------------- 1 | # Whats New 2 | 3 | ## What's New in Premiere Pro CS5? 4 | 5 | In the Effects panel, video filters now appear with badges to advertise if they support YUV, 32- bit, and accelerated rendering. 6 | 7 | The user can filter the list of effects to show only the effects that support those rendering modes. Video filters will automatically receive YUV and 32-bit badges if they advertise support using the existing `fsGetPixelFormatsSupported`. 8 | 9 | Custom badges can also be created. See Effect Badging for more information. 10 | 11 | --- 12 | 13 | ## What's New in Premiere Pro CS3? 14 | 15 | Checkbox controls are now supported directly in the Effect Controls panel. 16 | 17 | Filters can specify whether or not they want a setup button in the Effect Controls panel during `fsHasSetupDialog`, by returning `fsHasNoSetupDialog` or `fsNoErr`. 18 | 19 | Previously, this was set in the PiPL resource. 20 | -------------------------------------------------------------------------------- /docs/intro/getting-support.md: -------------------------------------------------------------------------------- 1 | # Getting Support and Providing Feedback 2 | 3 | Please read relevant sections of this document and view the included sample code before requesting assistance. Please direct questions regarding installation, configuration, or use of Adobe products to Adobe Technical Support. 4 | 5 | Having a solid understanding of digital video concepts is vital to developing plugins. This documentation assumes you understand basic video topics such as resolution, frame rates, field interlacing, pixel aspect ratio, bit depth, timecode, compression, color spaces, etc. You must also understand how your plugin will fit into a user's workflow in Premiere Pro. If you aren't yet familiar with Premiere Pro or video editing concepts, we recommend the Adobe Premiere Pro Classroom in a Book. 6 | 7 | Use the [Premiere Pro SDK forum](https://community.adobe.com/t5/forums/filteredbylabelpage/board-id/premiere-pro/label-name/sdk) to ask questions on the API and general integration. 8 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: ci 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | - main 8 | permissions: 9 | contents: write 10 | jobs: 11 | deploy: 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/checkout@v4 15 | with: 16 | fetch-depth: 0 17 | - name: Configure Git Credentials 18 | run: | 19 | git config user.name github-actions[bot] 20 | git config user.email 41898282+github-actions[bot]@users.noreply.github.com 21 | 22 | - uses: actions/setup-python@v5 23 | with: 24 | python-version: 3.x 25 | 26 | - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 27 | 28 | - uses: actions/cache@v4 29 | with: 30 | key: mkdocs-material-${{ env.cache_id }} 31 | path: .cache 32 | restore-keys: | 33 | mkdocs-material- 34 | 35 | - name: Install Python dependencies 36 | uses: py-actions/py-dependency-install@v4 37 | 38 | - run: mkdocs gh-deploy --force 39 | -------------------------------------------------------------------------------- /docs/_global/overrides/templates/print_site_cover_page.tpl: -------------------------------------------------------------------------------- 1 |
    2 | 3 | {% if config.site_name %} 4 |

    {{ config.site_name }}

    5 | {% endif %} 6 | 7 | {% if config.extra.homepage %} 8 | by

    {{ config.extra.homepage }}

    9 | {% endif %} 10 | 11 |
    12 | 13 | 14 | 15 | 16 | {% if config.site_description %} 17 | 18 | 19 | 20 | 21 | {% endif %} 22 | 23 | {% if config.site_url %} 24 | 25 | 26 | 27 | 28 | {% endif %} 29 | 30 | {% if config.repo_url %} 31 | 32 | 33 | 34 | 35 | {% endif %} 36 | 37 | {% if config.copyright %} 38 | 39 | 40 | 41 | 42 | {% endif %} 43 | 44 |
    Description{{ config.site_description }}
    Hosted at{{ config.site_url }}
    Repository{{ config.repo_url }}
    Copyright{{ config.copyright }}
    45 | -------------------------------------------------------------------------------- /docs/_global/scripts/update-common-components.py: -------------------------------------------------------------------------------- 1 | import os 2 | import shutil 3 | import tarfile 4 | import tempfile 5 | import urllib.request 6 | 7 | org_name = "docsforadobe" 8 | repo_name = "docsforadobe-mkdocs-config" 9 | destination_dir = "./docs/_global" 10 | 11 | def download_github_repo(org_name, repo_name, destination_dir): 12 | tar_url = f"https://api.github.com/repos/{org_name}/{repo_name}/tarball/main" 13 | 14 | response = urllib.request.urlopen(tar_url) 15 | 16 | if (response): 17 | with tempfile.TemporaryDirectory() as temp_dir: 18 | tar = tarfile.open(fileobj=response, mode="r|gz") 19 | tar_extraction_path = os.path.join(temp_dir, tar.firstmember.name) 20 | 21 | tar.extractall(path=temp_dir) 22 | 23 | # If already exist, remove first 24 | if (os.path.isdir(destination_dir)): 25 | shutil.rmtree(destination_dir) 26 | 27 | # Move from temp folder to destination folder 28 | shutil.move(tar_extraction_path, destination_dir) 29 | 30 | download_github_repo(org_name, repo_name, destination_dir) 31 | -------------------------------------------------------------------------------- /docs/universals/video-frames.md: -------------------------------------------------------------------------------- 1 | # Video Frames 2 | 3 | Premiere stores each video frame in a PPix structure. A PPixHand is a handle to a PPix. This structure should not be accessed directly, but manipulated using various suites such as the [PPix Suite](sweetpea-suites.md#ppix-suite), [PPix 2 Suite](sweetpea-suites.md#ppix-2-suite), [PPix Creator Suite](sweetpea-suites.md#ppix-creator-suite), and [PPix Creator 2 Suite](sweetpea-suites.md#ppix-creator-2-suite). 4 | 5 | Far from being just a boring buffer of RGB data, PPixes can contain a significant amount of information about a video frame, including: rectangle bounds (width, height), pixel aspect ratio, pixel format, field dominance, alpha interpretation, color space, gamma encoding, and more. 6 | 7 | In the pixel buffer itself, there may be padding between neighboring horizontal rows of pixels. So when iterating through the pixels in the buffer, don't assume that the first pixel on the next line is stored immediately after the last pixel on the current line. Honor the rowbytes, which is a measure of the size in bytes of a row of pixels, including any extra padding. 8 | 9 | Frames are guaranteed to be 16-byte aligned. 10 | -------------------------------------------------------------------------------- /docs/hardware/classid-filetype-subtype.md: -------------------------------------------------------------------------------- 1 | # ClassID, Filetype and Subtype 2 | 3 | All plugin types that support media must identify unique classID, filetype, and subtype. 4 | 5 | These are all four character codes, or 'fourCCs'. 6 | 7 | | Identifier | Purpose | 8 | |-|-| 9 | | `filetype` | Identifies the plugin's associated file type(s). Plugins create lists of filetypes they support. | 10 | | `subtype` | Differentiates between files of the same filetype. Identifies the codec or compression to be used. | 11 | | `classID` | With the new editing mode system starting in CS4, the classID is far less important. | 12 | | | It is used as part of the identification for exporters in the Editing Mode XML. | 13 | | | And plugins may share information with most other plugins running in the same process using the [ClassData Functions](classdata-functions.md). | 14 | -------------------------------------------------------------------------------- /docs/hardware/hardware-integration-components.md: -------------------------------------------------------------------------------- 1 | # Hardware Integration Components 2 | 3 | ## Importers 4 | 5 | Importers are used whenever frames of video or audio from a clip are needed. To give Premiere Pro the ability to read media that uses a new format or codec, develop an importer. See [Importers](../importers/importers.md) for more information. 6 | 7 | --- 8 | 9 | ## Exporters 10 | 11 | Exporters are used whenever Premiere Pro renders preview files, or performs an export on a clip or sequence. To give Premiere Pro the ability to write media that uses a new format or codec, develop an exporter. The exporter used to render preview files in the timeline is set in Sequence > Sequence Settings > Preview File Format. The exporter used for exports is chosen when the user selects File > Export > Media > File Type. See [Exporters](../exporters/exporters.md) for more information. 12 | 13 | --- 14 | 15 | ## Transmitters 16 | 17 | A transmitter handles the display of video on any external A/V hardware and secondary output. To give Premiere Pro the ability to play video out to hardware for preview and final playout, write a transmitter. See [Transmitters](../transmitters/transmitters.md) for more information. 18 | -------------------------------------------------------------------------------- /docs/intro/where-do-i-start.md: -------------------------------------------------------------------------------- 1 | # Where Do I Start 2 | 3 | Investigate the sample projects, and decide which one is closest to the functionality you want to provide. Clone it (changing names as appropriate), and build the plugin into the shared plugins folder. 4 | 5 | Launch Premiere Pro, attach the debugger, and set breakpoints at the plugin's entry point to see all communication between Premiere Pro and the plugin. The documentation is intended as a reference with detailed explanation where appropriate, but studying the interaction between Premiere Pro and plugins is the best way to understand it. 6 | 7 | Write plugins by modifying sample plugin source code. This will greatly simplify your efforts, and make it easier for us to help you. Feel free to explore and experiment with the API on your own once you're familiar with it, but please, resist the temptation to start from scratch; you'll only force yourself to repeat other developers' mistakes, including our own. 8 | 9 | If you run into behavior that seems wrong, see if you can reproduce the behavior using one of the unmodified sample projects. This can save you a lot of time, if you can determine whether the bug behavior was introduced by your modifications, or was already there to begin with. 10 | -------------------------------------------------------------------------------- /docs/intro/document-overview.md: -------------------------------------------------------------------------------- 1 | # Document Overview 2 | 3 | This introduction information is common to all the plugin types. 4 | 5 | All developers should read this chapter, and browse through chapters two and three before diving too deep into plugin development. 6 | 7 | [Resources](../resources/resources.md) is a short chapter that describes the Premiere Pro-specific resources used by plugins, including the Plugin Property List (PiPL). 8 | 9 | [Universals](../universals/universals.md) documents concepts, data types, and structures used throughout the APIs. It also describes suites and functions used by more than one type of plugin. 10 | 11 | [Hardware](../hardware/hardware.md) introduces Media Abstraction, used by hardware integrators and software developers to integrate with Premiere and accelerate specific workflows. 12 | 13 | This document is designed to be read non-linearly. You can browse through the topics from the bookmarks that appear in the left-hand panel in Acrobat, or the right-hand panel in the Preview application on macOS. A simple search for a well-chosen keyword will also turn up much information on any given topic. 14 | 15 | --- 16 | 17 | ## Documentation Conventions 18 | 19 | Functions, structure names and general C/C++ code are in Courier; `MyStruct.member` and `MyFunction()` 20 | 21 | Underlined text in light blue is hyperlinked. Premiere selectors are italicized; *imGetPrefs*. 22 | -------------------------------------------------------------------------------- /docs/ae-transition-extensions/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ## Setting up the Sample Project 4 | 5 | If you are developing an transition, begin with the SDK_CrossDissolve sample project, progressively replacing its functionality with your own. Refer to [Introduction](../index.md) for general instructions on how to build sample projects. 6 | 7 | In addition to those general instructions, the sample project is also dependent on the After Effects SDK. Download it here. On Windows, create an environment variable pointing to it named "AE_SDK_BASE_PATH", so that the compiler will find the AE headers that the project includes. On 8 | 9 | MacOS, in XCode > Preferences > Locations > Custom Paths, specify AE_SDK_BASE_PATH to be the root folder of the AE SDK you have downloaded and unzipped. 10 | 11 | As of version 15.4, Premiere Pro no longer supports OpenCL. 12 | 13 | If your transition uses CUDA, you'll need to download the CUDA SDK. On Windows, create an environment variable pointing to it named "CUDA_SDK_BASE_PATH", so that the linker will find the right libraries. 14 | 15 | --- 16 | 17 | ## Compatibility Considerations 18 | 19 | For compatibility with plugin hosts that doesn't support the AE Transition Extensions, a plugin should check first for the existence of the PF_TransitionSuite suite. If it isn't available, the plugin should act as a normal effect. This is demonstrated in the SDK_CrossDissolve sample project. 20 | -------------------------------------------------------------------------------- /docs/export-controllers/export-controllers.md: -------------------------------------------------------------------------------- 1 | # Export Controllers 2 | 3 | An export controller can drive any exporter to generate a file in any format and perform custom post-processing operations. 4 | 5 | An export controller adds its own custom menu item to the File > Export submenu. When the user chooses the menu item, the plugin is called with a TimelineID, which represents the current sequence. Although details on the current sequence are not passed in, the export controller can use the [Sequence Info Suite](../universals/sweetpea-suites.md#sequence-info-suite) to query for various properties. The export controller can then optionally display any custom modal UI to allow the user to set any parameters for the export. 6 | 7 | The Export Controller must provide its own UI, calling ExportFile in the Export Controller Suite, which takes the TimelineID, a path to an exporter preset, and a path for the output. This tells Premiere Pro to handle the export, displaying progress. The call will return either a success value, an error, or that the user canceled. During the export, the UI will be blocked, just as when doing a standard export that doesn't use the Adobe Media Encoder Render Queue. 8 | 9 | Once Premiere Pro completes the export, the call will return to the export controller. The plugin can then perform any post-processing operations, such as transferring the newly exported file over the network, or registering the file in an asset management system. 10 | -------------------------------------------------------------------------------- /docs/intro/localization.md: -------------------------------------------------------------------------------- 1 | # Localization 2 | 3 | The language used by Premiere Pro is decided by the user during installation. 4 | 5 | Plugins can determine this setting from the following locations: 6 | 7 | On Windows, in the registry at `HKEY_CURRENT_USER\Software\Adobe\Premiere Pro\[version]`, in a key named `"Language"`. 8 | 9 | On macOS, at `~/Library/Preferences/com.Adobe.Premiere Pro.[version].plist`, at `Root > Language`. 10 | 11 | The string will be set to one of the values below by Premiere Pro at startup. 12 | 13 | | Language | String | 14 | | ------------------------------------ | ------- | 15 | | English | `en_US` | 16 | | French | `fr_FR` | 17 | | German | `de_DE` | 18 | | Italian | `it_IT` | 19 | | Japanese | `ja_JP` | 20 | | Spanish | `es_ES` | 21 | | Korean | `ko_KR` | 22 | | Chinese (new in CC) | `zh_CN` | 23 | | Russian (new in CC 2014) | `ru_RU` | 24 | | Brazilian Portugese (new in CC 2014) | `pt_BR` | 25 | 26 | Changing the string will not change the language Premiere Pro runs in, unless you override the application language by placing a file in the following location: 27 | 28 | Windows: `[App installation folder]\lang-override.txt` 29 | 30 | macOS: `[App Installation folder]/[Premiere Pro application package]/Contents/lang-override.txt` 31 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/PrGPUFilter-function-table.md: -------------------------------------------------------------------------------- 1 | # PrGPUFilter Function Table 2 | 3 | PrGPUFilter is a structure consisting of the following functions that a effect/transition can implement. 4 | 5 | | Selector | Optional | Description | 6 | | --------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | 7 | | [CreateInstance](function-descriptions.md#createinstance) | No | Allocate and initialize any GPU resources. | 8 | | [DisposeInstance](function-descriptions.md#disposeinstance) | No | Release GPU resources. | 9 | | [GetFrameDependencies](function-descriptions.md#getframedependencies) | Yes | If the rendered result of the effect/transition depends on frames other than the input frame, specify these here. | 10 | | [PreCompute](function-descriptions.md#precompute) | Yes | Precompute. | 11 | | [Render](function-descriptions.md#render) | No | Render. | 12 | -------------------------------------------------------------------------------- /docs/intro/debugging-plugins.md: -------------------------------------------------------------------------------- 1 | # Debugging plugins 2 | 3 | Once you've got the plugin building directly into the plugins folder as explained above, here's how to specify Premiere Pro as the application to run during debug sessions: 4 | 5 | ## Windows 6 | 7 | 1. In the Visual Studio solution, in the Solution Explorer panel, choose the project you want to debug 8 | 2. Right-click it and choose Set as StartUp Project 9 | 3. Right-click it again and choose Properties 10 | 4. In Configuration Properties > Debugging > Command, provide the path to the executable file of the host application the plugins will be running in (this may be Premiere Pro or After Effects) 11 | 5. From there you can either hit the Play button, or you can launch the application and later at any point choose Debug > Attach to Process… 12 | 13 | ## macOS 14 | 15 | 1. In XCode, in the Project Navigator, choose the xcodeproj you want to debug 16 | 2. Choose Product > Scheme > Edit Scheme… 17 | 3. Under Run, in the Info tab, for Executable, choose the host application the plugins will be running in (this may be Premiere Pro or After Effects) 18 | 4. From there you can either hit the Play button to build and run the current scheme, or you can launch the application and later at any point choose Debug > Attach to Process. 19 | 20 | Another way to do this in Visual Studio is by placing a line of code 21 | 22 | ```cpp 23 | _asm int 3; 24 | ``` 25 | 26 | or 27 | 28 | ```cpp 29 | DebugBreak(); 30 | ``` 31 | 32 | You will then receive the Microsoft error reporting message, but if you hit the Debug button you will enable Just-In-Time Debugging and can attach to the process. 33 | -------------------------------------------------------------------------------- /docs/importers/importers.md: -------------------------------------------------------------------------------- 1 | # Importers 2 | 3 | Importers provide video, audio and/or closed captioning from the media source. This source can be a single file, a set of files, a communication link between another application, etc. 4 | 5 | Standard importers appear as choices in the File > Import dialog, in the Files of type drop-down menu. Importers can support movies, still images, series of still images, and/or audio. If your importer provides enhanced support for a format already supported by another importer that ships with Premiere, set a high value in imImportInfoRec.priority to give your importer the first opportunity to handle the file. 6 | 7 | Synthetic importers synthesize source material, rather than reading from disk. They appear in the File > New menu. 8 | 9 | Custom importers are a special type of synthetic importer, implemented to better support titlers. Custom importers can create files on disk; synthetic importers don't. Custom importers either create new media or import existing media handled by the importer. After the file is created, the media is treated like a standard file by the host application. Additionally, the media can be modified by the importer when the user double-clicks on it in the Project Panel. 10 | 11 | | Importer Type | Reads from disk | Creates clips | Menu Location | 12 | | ------------- | --------------- | ------------- | ------------------------ | 13 | | Standard | Yes | No | File > Import | 14 | | Synthetic | No | Yes | File > New | 15 | | Custom | Yes | Yes | File > New File > Import | 16 | 17 | If you've never developed an importer before, you can skip [What's New](whats-new.md), and go directly to [Getting Started](getting-started.md). 18 | -------------------------------------------------------------------------------- /docs/_global/css/global-syntax-highlight.css: -------------------------------------------------------------------------------- 1 | /* Set light & dark mode syntax highlight */ 2 | 3 | @media screen { 4 | /* Light mode */ 5 | [data-md-color-scheme="default"] { 6 | --md-code-fg-color: #36464e; 7 | --md-code-bg-color: #f5f5f5; 8 | --md-code-hl-color: #4287ff; 9 | 10 | --md-code-hl-constant-color: #6e59d9; 11 | --md-code-hl-function-color: #a846b9; 12 | --md-code-hl-keyword-color: #3f6ec6; 13 | --md-code-hl-number-color: #d52a2a; 14 | --md-code-hl-special-color: #db1457; 15 | --md-code-hl-string-color: #1c7d4d; 16 | --md-code-hl-comment-color: var(--md-default-fg-color--light); 17 | --md-code-hl-generic-color: var(--md-default-fg-color--light); 18 | --md-code-hl-name-color: var(--md-code-fg-color); 19 | --md-code-hl-operator-color: var(--md-default-fg-color--light); 20 | --md-code-hl-punctuation-color: var(--md-default-fg-color--light); 21 | --md-code-hl-variable-color: var(--md-default-fg-color--light); 22 | } 23 | 24 | /* Dark mode */ 25 | [data-md-color-scheme="slate"] { 26 | --md-code-bg-color: #272a35; 27 | --md-code-fg-color: #d5d8e2d1; 28 | --md-code-hl-color: #2977ff; 29 | 30 | --md-code-hl-constant-color: #9383e2; 31 | --md-code-hl-function-color: #c973d9; 32 | --md-code-hl-keyword-color: #6791e0; 33 | --md-code-hl-number-color: #e6695b; 34 | --md-code-hl-special-color: #f06090; 35 | --md-code-hl-string-color: #2fb170; 36 | --md-code-hl-comment-color: var(--md-default-fg-color--light); 37 | --md-code-hl-generic-color: var(--md-default-fg-color--light); 38 | --md-code-hl-name-color: var(--md-code-fg-color); 39 | --md-code-hl-operator-color: var(--md-default-fg-color--light); 40 | --md-code-hl-punctuation-color: var(--md-default-fg-color--light); 41 | --md-code-hl-variable-color: var(--md-default-fg-color--light); 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /docs/universals/time.md: -------------------------------------------------------------------------------- 1 | # Time 2 | 3 | There are two different representations of time: `scale over sampleSize`, and `ticks`. 4 | 5 | --- 6 | 7 | ## scale over sampleSize 8 | 9 | The first representation of time uses value/scale/`sampleSize` components, either separated, or combined in a TDB_TimeRecord structure. scale over `sampleSize` defines the timebase. For example, to represent the NTSC standard of 29.97 frames per second, `scale` / `sampleSize = 30000` / 1001. To represent the PAL standard of 25 frames per second, 25 / 1. 10 | 11 | To represent the 24p standard of 23.976, 23976 / 1000, or 24000 / 1001. To represent most other timebases, use `sampleSize = 1`, and scale is the frame rate (e.g. 15, 24, 30 fps, etc). Another way of thinking about scale and `sampleSize` is that `sampleSize` is the duration of a frame of video, and scale is that duration of a second of video. 12 | 13 | `value` is the time in the timebase given by `scale` over `sampleSize`. So, for example, 30 frames with a sampleSize of 1001 have a value of 30030. 14 | 15 | To convert `value` to seconds, divide by scale. To convert `value` to frames, divide by `sampleSize`. 16 | 17 | Sometimes, as when handling audio-only media, `sampleSize` refers to a sample of audio, and `sampleSize = 1`. In this case, scale is the audio sampling rate (22050, 32000, 44100, 48000 Hz, etc). 18 | 19 | --- 20 | 21 | ## PrTime 22 | 23 | Most newer areas of the API use a tick-based time value that is stored in a signed 64-bit integer. Variables that use this new format are of type PrTime. When a frame rate is represented as a PrTime, the frame rate is the number of ticks in a frame duration. 24 | 25 | The current number of ticks per second must be retrieved using the callback in the [Time Suite](sweetpea-suites.md#time-suite). This rate is guaranteed to be constant for the duration of the application's run-time. 26 | -------------------------------------------------------------------------------- /docs/_global/hooks/inline_pre_to_code_fence.py: -------------------------------------------------------------------------------- 1 | # Converts inline 
    code
    blocks to pygments-highlighted html 2 | # Custom hook to highlight and format 
    code
    code
    blocks 3 | # 4 | # This is used for 
     blocks embedded in tables, as these otherwise are skipped by pygments
 5 | #
 6 | # Note: It's possible this can be done better with Python-markdown inline patterns (https://python-markdown.github.io/reference/markdown/inlinepatterns),
 7 | #   but the below works For Now
 8 | 
 9 | import re
10 | import markdown
11 | 
12 | import mkdocs
13 | from mkdocs.structure.pages import Page
14 | from mkdocs.config.defaults import MkDocsConfig
15 | from mkdocs.structure.files import Files
16 | 
17 | from pymdownx.highlight import HighlightExtension
18 | 
19 | # Get current mkdocs config
20 | user_extensions = MkDocsConfig.markdown_extensions.__dict__.get('configdata');
21 | highlight_config = dict()
22 | 
23 | if 'pymdownx.highlight' in user_extensions:
24 |     highlight_config = user_extensions.get('pymdownx.highlight')
25 | 
26 | ExistingHighlighter = HighlightExtension().get_pymdownx_highlighter()(**highlight_config)
27 | 
28 | def on_page_content(html: str, page: Page, config: MkDocsConfig, files: Files, **kwargs):
29 |     def inline_pre_to_code_fence(match):
30 |         raw = match.group()
31 | 
32 |         ## Check for language
33 |         lang = ''
34 |         langmatch = re.search('lang="(.*?)"', raw)
35 | 
36 |         if langmatch:
37 |             lang = langmatch.group(1)
38 | 
39 |         ## Remove first tag
40 |         pre = re.sub('', '', raw)
41 | 
42 |         ## Strip end tag
43 |         pre = re.sub('
    ', '', pre) 44 | 45 | ## Swap html linebreaks 46 | pre = re.sub('
    ', '\n', pre) 47 | 48 | return ExistingHighlighter.highlight(pre, lang) 49 | 50 | result = re.sub('(.+)', inline_pre_to_code_fence, html) 51 | 52 | return result 53 | -------------------------------------------------------------------------------- /docs/universals/memory-management.md: -------------------------------------------------------------------------------- 1 | # Memory Management 2 | 3 | Premiere Pro has a media cache in which it stores imported frames, intermediate frames (intermediate stages of a render), fully rendered frames, and audio. This cache is sized based on a specific percentage of physical memory, taking into account if multiple Adobe applications are also running. 4 | 5 | Premiere Pro manages this cache itself, so as it adds new items to the cache, it flushes least recently used items. 6 | 7 | --- 8 | 9 | ## What Really is a Memory Problem? 10 | 11 | Often, users monitoring memory usage are alarmed when they see memory growing to a specific point during a render or playback. When the memory doesn't drop right back down after a render or playback, they might think they have found a memory leak. However, keeping in mind the function of the Premiere Pro media cache, this behavior is to be expected. 12 | 13 | Memory contention between plugins and the rest of Premiere Pro can lead to memory problems. If a plugin allocates a significant amount of memory and the Premiere Pro media cache has not accounted for it, this means there is less free memory available after the media cache grows to the predefined size. Even if Premiere Pro does not completely run out of memory, limited memory can cause memory thrashing as memory is moved around to make room for video frames, which in turn can cause poor performance. 14 | 15 | --- 16 | 17 | ## Solutions for Memory Contention 18 | 19 | The best approach to reduce memory contention is to reduce the memory requirements of each plugin. However, if the memory requirements of a plugin are significant, it should also use the [Memory Manager Suite](sweetpea-suites.md#memory-manager-suite) to report any memory usage that would not already be accounted for. 20 | 21 | Frames allocated using the [PPix Creator Suite](sweetpea-suites.md#ppix-creator-suite) are accounted for, but any memory allocated using the old PPix and Memory functions are not automatically accounted for. 22 | -------------------------------------------------------------------------------- /docs/hardware/classdata-functions.md: -------------------------------------------------------------------------------- 1 | # ClassData Functions 2 | 3 | All plugin types that support media can use these callbacks to share information associated with their classID. 4 | 5 | For example, these plugins can confirm their hardware is present and operational using the ClassData functions. 6 | 7 | They all call `getClassData` during initialization. If `getClassData` returns 0, the module checks for and initialize the hardware. 8 | 9 | It then calls setClassData to store information about the current context. Use handles, not pointers, for storing info. 10 | 11 | ```c++ 12 | typedef struct { 13 | SetClassDataFunc setClassData; 14 | GetClassDataFunc getClassData; 15 | } ClassDataFuncs, *ClassDataFuncsPtr; 16 | ``` 17 | 18 | --- 19 | 20 | ## Methods 21 | 22 | ### setClassData 23 | 24 | `setClassData` 25 | 26 | #### Description 27 | 28 | Writes class data, destroys previous data. 29 | 30 | Note that all plugins that share the data must use the same data structure. 31 | 32 | ```cpp 33 | int setClassData ( 34 | unsigned int theClass, 35 | void *info); 36 | ``` 37 | 38 | #### Parameters 39 | 40 | | Parameter | Type | Description | 41 | | ---------- | ----------------- | ------------------------------------------------------------------ | 42 | | `theClass` | Unsigned int | The class being set. Use a unique 4-byte code. | 43 | | `info` | Pointer or handle | the class data to be set. It can be used as a pointer or a handle. | 44 | 45 | --- 46 | 47 | ### getClassData 48 | 49 | `getClassData` 50 | 51 | Retrieves the class data for the given class. 52 | 53 | ```cpp 54 | int getClassData ( 55 | unsigned int theClass); 56 | ``` 57 | 58 | | Parameter | Type | Description | 59 | | ---------- | ---------------- | ------------------------------------- | 60 | | `theClass` | Unsigned integer | The class for which to retrieve data. | 61 | -------------------------------------------------------------------------------- /docs/control-surfaces/control-surfaces.md: -------------------------------------------------------------------------------- 1 | # Control Surfaces 2 | 3 | A control surface plugin can interface with a hardware control surface. This is the API that provides built-in support for EUCON and Mackie devices to control audio mixing and basic transport controls. The API supports two-way communication with Premiere Pro, so that hardware faders, VU meters, etc are in sync with the application. 4 | 5 | Compile the sample plugin into a subfolder of the main application folder: `Plugins\\ ControlSurface\\` 6 | 7 | You should see the plugin in the PPro UI in Preferences > Control Surface, when you hit the Add button, as one of the options in the Device Class drop-down next to Mackie and EUCON (currently shows as "SDK Control Surface Sample"). 8 | 9 | You'll want to implement handlers for any relevant functions defined in the plugin suites here: `adobesdk\controlsurface\plugin` 10 | 11 | And to do that, you can use any APIs to call into the host defined in the host suites here: `adobesdk\controlsurface\host` 12 | 13 | --- 14 | 15 | ## Calling Sequence 16 | 17 | When the application is launched, the control surface plugins are loaded, and the entry point is called. The host ID and API version is passed in, and the plugin passes back ADOBESDK_ControlSurfacePluginFuncs, an array of function pointers. 18 | 19 | Next, the Startup() function is called, where the plugin registers a suite of functions as defined in ControlSurfacePluginSuite.h. For each base class it will inherit from (defined in adobesdkcontrolsurfacepluginwrapper), it calls RegisterSuite(). These suites are the way for the host application to call the control surface plugin later on. There are separate base classes for the transport controls, audio mixer, Lumetri Color controls, and more. 20 | 21 | Then, CreatePluginInstance() is called. When a project is opened, Connect() is called. Here the plugin instantiates a ControlSurface object, which inherits from any of the previously mentioned base classes. It acquire any host suites it needs, and then it passes back a reference to the ControlSurface object. 22 | 23 | --- 24 | 25 | ## Getting Started 26 | 27 | Reach out as necessary, for further guidance. 28 | -------------------------------------------------------------------------------- /docs/transmitters/transmitters.md: -------------------------------------------------------------------------------- 1 | # Transmitters 2 | 3 | This API provides support for pushing video, audio, and closed captions to external hardware. Transmitters can be specified by the user in Preferences > Playback. Other plugins such as importers and effects with settings preview dialogs can send video out to the active transmitter, opening up new possibilities for hardware monitoring. Transmit plugins are supported in Premiere Pro, After Effects (starting in CC 2014), and Character Animator. 4 | 5 | When a new transmitter instance is created, it is asked to describe the format(s) it wishes to receive the rendered video in. A transmitter plugin can request different formats depending on the source clip or timeline format. The host application will handle all the conversions to the desired video format. As an example, a transmitter instance may specify that it can only handle a fixed width and height, but any pixel format. Besides video conversions, the host handles scheduling for prefetching the media and asynchronous rendering. 6 | 7 | A transmitter may leave the audio to be played by the host, through the system's sound drivers (ASIO or CoreAudio). Or, if a transmitter wants to handle the audio itself to send it to the external hardware, it can request audio using GetNextAudioBuffer in the [Playmod Audio Suite](suites.md#playmod-audio-suite). 8 | 9 | On playback, the host provides the transmitter with a clock callback, which the transmitter must call to update the host with the new time every frame. This allows the transmitter to orchestrate the audio/video sync. 10 | 11 | Transmitters can use the [Captioning Suite](../universals/sweetpea-suites.md#captioning-suite) to get any closed captions for the sequence. 12 | 13 | Transmitters do not need to call the Playmod Device Controller suite to handle Export to Tape. This is handled at the player level. 14 | 15 | --- 16 | 17 | ## What's New in Premiere Pro 24.0? 18 | 19 | Support for additional audio output devices has been added. 20 | 21 | --- 22 | 23 | ## What's New in Premiere Pro CS6.0.2? 24 | 25 | A transmitter can now provide strings to label its audio channels, in `tmAudioMode.outOutputAudioNames`. These strings will be used for the Audio Output Mapping preferences, rather than the default strings. 26 | -------------------------------------------------------------------------------- /docs/video-filters/selector-table.md: -------------------------------------------------------------------------------- 1 | # Selector Table 2 | 3 | This table summarizes the various selector commands a video filter can receive. 4 | 5 | | Selector | Optional? | Description | 6 | |-------------|-----------|--------------------------------------------------------| 7 | | [fsInitSpec](selector-descriptions.md#fsinitspec) | Yes | Allocate and initialize your parameters with default values without popping a modal setup dialog. | 8 | | [fsHasSetupDialog](selector-descriptions.md#fshassetupdialog) | Yes | New for Premiere Pro CS3. Specify whether or not the filter has a setup dialog. | 9 | | [fsSetup](selector-descriptions.md#fssetup) | Yes | Allocate memory for your parameters if necessary. | 10 | | | | Display your modal setup dialog with default parameter values or previously stored values. | 11 | | | | Save the new values to `specsHandle`. | 12 | | [fsExecute](selector-descriptions.md#fsexecute) | No | Filter the video using the stored parameters from `specsHandle`. | 13 | | | | Be aware of interlaced video, and don't overlook the alpha channel! | 14 | | [fsDisposeData](selector-descriptions.md#fsdisposedata) | Yes | Dispose of any instance data created during `fsExecute`. | 15 | | [fsCanHandlePAR](selector-descriptions.md#fscanhandlepar) | Yes | Tell Premiere how your effect handles pixel aspect ratio. | 16 | | [fsGetPixelFormatsSupported](selector-descriptions.md#fsgetpixelformatssupported) | Yes | Gets pixel formats supported. Called iteratively until all formats have been given. | 17 | | [fsCacheOnLoad](selector-descriptions.md#fscacheonload) | Yes | Return fsDoNotCacheOnLoad to disable plugin caching for this filter. | 18 | -------------------------------------------------------------------------------- /docs/_global/mkdocs.yml: -------------------------------------------------------------------------------- 1 | # Shared config for all repos 2 | copyright: All content is copyright Adobe Systems Incorporated. 3 | 4 | extra: 5 | homepage: https://docsforadobe.dev 6 | 7 | # Using overrides here as we can't inherit "extra_css" 8 | overrides: 9 | extra_css: 10 | - docs/_global/css/global.css 11 | - docs/_global/css/global-syntax-highlight.css 12 | extra_javascript: 13 | - docs/_global/js/global.js 14 | 15 | hooks: 16 | - docs/_global/hooks/inline_pre_to_code_fence.py 17 | - docs/_global/hooks/merge_inherited_config.py 18 | 19 | markdown_extensions: 20 | admonition: {} 21 | markdown_grid_tables: {} 22 | md_in_html: {} 23 | pymdownx.details: {} 24 | pymdownx.highlight: 25 | line_spans: __span 26 | pygments_lang_class: true 27 | pymdownx.superfences: {} 28 | pymdownx.tabbed: 29 | alternate_style: true 30 | pymdownx.tasklist: 31 | custom_checkbox: true 32 | toc: 33 | title: Page Contents 34 | permalink: true 35 | toc_depth: 3 36 | 37 | not_in_nav: | 38 | _global 39 | 40 | plugins: 41 | git-revision-date-localized: {} 42 | search: 43 | separator: '[\s\-,\.:!=\[\]()"/]+' 44 | 45 | # Note: print-site must be last! 46 | print-site: 47 | add_cover_page: true 48 | add_print_site_banner: true 49 | cover_page_template: "docs/_global/overrides/templates/print_site_cover_page.tpl" 50 | print_page_title: "Offline Docs" 51 | print_site_banner_template: "docs/_global/overrides/templates/print_site_banner.tpl" 52 | 53 | theme: 54 | name: material 55 | custom_dir: docs/_global/overrides 56 | features: 57 | - announce.dismiss 58 | - content.action.edit 59 | - content.action.view 60 | - content.code.copy 61 | - search.highlight 62 | - search.suggest 63 | - toc.follow 64 | palette: 65 | # Palette toggle for dark mode 66 | - media: "(prefers-color-scheme: dark)" 67 | primary: black 68 | scheme: slate 69 | toggle: 70 | icon: material/brightness-4 71 | name: Switch to light mode 72 | 73 | # Palette toggle for light mode 74 | - media: "(prefers-color-scheme: light)" 75 | primary: white 76 | scheme: default 77 | toggle: 78 | icon: material/brightness-7 79 | name: Switch to dark mode 80 | -------------------------------------------------------------------------------- /docs/transmitters/suites.md: -------------------------------------------------------------------------------- 1 | # Suites 2 | 3 | For information on how to acquire and manage suites, as well as information on more suites that are available to other plugin types beyond just transmitters, see [SweetPea Suites](../universals/sweetpea-suites.md). 4 | 5 | --- 6 | 7 | ## Playmod Audio Suite 8 | 9 | This suite is used to play audio during playback. There are many more functions that were used by players, still documented in the players chapter. Here we will only consider the single call in the suite that is relevant to transmitters. 10 | 11 | ### Host-Based, or Plugin Based Audio? 12 | 13 | A transmitter has two choices for playing audio: it can ask the host to play the audio through the audio device selected by the user, or it can get audio buffers from the host and handle its own playback of audio. 14 | 15 | ### GetNextAudioBuffer 16 | 17 | Retrieves from the host the next contiguous requested number of audio sample frames, specified in `inNumSampleFrames`, in `inInBuffers` as arrays of uninterleaved floats. 18 | 19 | The plugin must manage the memory allocation of `inInBuffers`, which must point to n buffers of floating point values of length `inNumSampleFrames`, where n is the number of channels. This call is only available if `InitPluginAudio` was used. 20 | 21 | Returns: 22 | 23 | - `suiteError_NoError`, 24 | - `suiteError_PlayModuleAudioNotInitialized`, or 25 | - `suiteError_PlayModuleAudioNotStarted` 26 | 27 | ```cpp 28 | prSuiteError (*GetNextAudioBuffer)( 29 | csSDK_int32 inPlayID, 30 | float** inInBuffers, 31 | float** outOutBuffers, 32 | unsigned int inNumSampleFrames); 33 | ``` 34 | 35 | | Parameter | Description | 36 | |-|-| 37 | | `inInBuffers` | Currently unused in CS6. | 38 | | | A pointer to an array of buffers holding `inNumSampleFrames` input audio in each buffer, corresponding to the total number of available input channels. | 39 | | `outOutBuffers` | A pointer to an array of buffers `inNumSampleFrames` long into which the host will write the output audio. | 40 | | | There must be N buffers, where N is the number of output channels for the output channel type specified in `InitPluginAudio`. | 41 | | `inNumSampleFrames` | The size of each of the buffers in the array in both `inInBuffers` and `outOutBuffers`. | 42 | 43 | --- 44 | 45 | ## Transmit Invocation Suite 46 | 47 | This suite can be used by other types of plugins to push frames to transmitters. 48 | 49 | For example, an effect or titler with a modal setup dialog could push frames to the output. 50 | -------------------------------------------------------------------------------- /docs/resources/pipl-resource.md: -------------------------------------------------------------------------------- 1 | # plugin Property Lists (PiPL) Resource 2 | 3 | For many plugin types, Premiere loads a PiPL (Plugin Property List) resource. The PiPL is described in a file with a ".r" extension. 4 | 5 | The complete PiPL syntax is described in PiPL.r. 6 | 7 | You'll notice that PiPLs are really old. A vestige of 68k macOS programming, they spread to Windows. However, if you develop from the sample projects, you shouldn't have to do anything to get them to build properly for Latin languages. 8 | 9 | --- 10 | 11 | ## Which Types of Plugins Need PiPLs? 12 | 13 | Exporters do not need PiPLs. 14 | 15 | Standard importers do not need PiPLs. Synthetic and custom importers use a basic PiPL to specify their name, and the match name that Premiere uses to identify them. The name appears in the File > New menu. 16 | 17 | Video filters use an extended PiPL to specify their name, the match name that Premiere uses to identify them, the bin they go in, how they handle pixel aspect ratio, whether or not they have randomness, and their parameters. 18 | 19 | For more information on the `ANIM_FilterInfo` and `ANIM_ParamAtom`, see the resources section in [Video Filters](../video-filters/video-filters.md). 20 | 21 | --- 22 | 23 | ## A Basic PiPL Example 24 | 25 | ```cpp 26 | #define plugInName "SDK Custom Import" 27 | #define plugInMatchName "SDK Custom Import" 28 | 29 | resource 'PiPL' (16000) { 30 | { 31 | 32 | // The plugin type 33 | Kind {PrImporter}, 34 | 35 | // The name as it will appear in a Premiere menu, this can be localized 36 | Name {plugInName}, 37 | 38 | // The internal name of this plugin - do not localize this. This is used for both Premiere and After Effects plugins. 39 | AE_Effect_Match_Name {plugInMatchName} 40 | 41 | // Transitions and video filters define more PiPL attributes here 42 | } 43 | 44 | }; 45 | ``` 46 | 47 | --- 48 | 49 | ## How PiPLs Are Processed By Resource Compilers 50 | 51 | On macOS, .r files are processed natively by XCode, as a Build Phase of type Build Carbon Resources. This step is already set for the sample projects. 52 | 53 | On Windows, .r files are processed with CnvtPiPL.exe, which creates an .rcp file based upon custom build steps in the project. The .rcp file is then included in the .rc file along with any other resources the plugin uses. These custom build steps are already in place in the sample projects. 54 | 55 | To view them, open up the sample project in .NET. In the Solution Explorer, right-click the .r file and choose Properties. In the dialog, choose the Custom Build Step folder. The Command 56 | 57 | Line contains the script for executing the CnvtPiPL.exe. Unless you are using a different compiler than the support compiler, or adding support for Asian languages, you should not need to modify the custom build steps. This script may also be found as a text file in the SDK at `\\Examples\\Resources\\Win\\Custom Build Steps.txt`. This text file also describes the additional switches used for Asian languages. 58 | -------------------------------------------------------------------------------- /docs/history.md: -------------------------------------------------------------------------------- 1 | # Version History 2 | 3 | | Date | Maintainer | Version | 4 | | ----------------- | --------------------------- | ----------------------------------- | 5 | | 2 Feb 2025 | Bruce Bullis | Version 26.0 | 6 | | 17 Oct 2025 | Bruce Bullis | Version 25.6 | 7 | | 6 Oct 2021 | Sanaz Golbabaei | Version 22.0 | 8 | | 8 May 2020 | Bruce Bullis | Version 14.2 | 9 | | 1 May 2019 | Bruce Bullis | Version 13.1 | 10 | | 1 November 2018 | Bruce Bullis | Version CC 13.0 | 11 | | 16 July 2018 | Zac Lam | Version CC 13.0 pre-release | 12 | | 13 November 2017 | Zac Lam | Version CC 12.0 | 13 | | 6 April 2017 | Zac Lam | Version CC 2017.1 | 14 | | 4 November 2016 | Zac Lam | Version CC 2017 | 15 | | 4 August 2015 | Zac Lam | Version CC 2015 | 16 | | 16 June 2014 | Zac Lam | Version CC 2014 | 17 | | 21 October 2013 | Zac Lam | Version CC October release | 18 | | 16 July 2013 | Zac Lam | Version CC | 19 | | 19 June 2012 | Zac Lam | Version CS6 release 2 | 20 | | 30 April 2012 | Zac Lam | Version CS6 release 1 | 21 | | 2 May 2011 | Zac Lam | Version CS5.5 | 22 | | 28 April 2010 | Zac Lam | Version CS5 | 23 | | 21 September 2009 | Zac Lam | Version CS4 | 24 | | 5 October 2007 | Zac Lam | Version CS3 | 25 | | 13 July 2006 | Zac Lam | Version 2.0 release 2 | 26 | | 17 January 2006 | Zac Lam | Version 2.0 release 1 | 27 | | 25 May 2004 | Zac Lam | Version 1.5 | 28 | | 21 August 2003 | Zac Lam | Version 1.0 (Premiere Pro) | 29 | | 19 July 2002 | Zac Lam & Bruce Bullis | Version 6.5 | 30 | | 10 May 2001 | Bruce Bullis | Version 6 release 2 | 31 | | 10 December 2000 | Bruce Bullis & Eric Sanders | Version 6 release 1 | 32 | | 20 April 1998 | Brian Andrews | Version 5 | 33 | | 9 February 1996 | Brian Andrews | Version 4.2 | 34 | | 13 February 1995 | Matt Foster, Nick Schlott | Version 4.0 - first Windows release | 35 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/function-descriptions.md: -------------------------------------------------------------------------------- 1 | # Function Descriptions 2 | 3 | ## CreateInstance 4 | 5 | ```cpp 6 | prSuiteError (*CreateInstance)( 7 | PrGPUFilterInstance* ioInstanceData); 8 | ``` 9 | 10 | Creates a GPU filter instance representing an effect or transition on a track item. 11 | 12 | Returning an error from CreateInstance will cause this node to be rendered in software for the current set of parameters. 13 | 14 | Unlike software instances of effects and transitions, GPU instances are created and disposed whenever an effect parameter changes. 15 | 16 | This allows an effect have more flexibility about opting-in for GPU rendering, depending on the parameters. Separate instances may be called concurrently. 17 | 18 | --- 19 | 20 | ## DisposeInstance 21 | 22 | ```cpp 23 | prSuiteError (*DisposeInstance)( 24 | PrGPUFilterInstance* ioInstanceData); 25 | ``` 26 | 27 | Cleanup any resources allocated during CreateInstance. 28 | 29 | --- 30 | 31 | ## GetFrameDependencies 32 | 33 | ```cpp 34 | prSuiteError (*GetFrameDependencies)( 35 | PrGPUFilterInstance* inInstanceData, 36 | const PrGPUFilterRenderParams* inRenderParams, 37 | csSDK_int32* ioQueryIndex, 38 | PrGPUFilterFrameDependency* outFrameDependencies); 39 | ``` 40 | 41 | Return dependency information about a render, or nothing if only the current frame is required. 42 | 43 | Increment `ioQueryIndex` for additional dependencies. 44 | 45 | --- 46 | 47 | ## PreCompute 48 | 49 | ```cpp 50 | prSuiteError (*Precompute)( 51 | PrGPUFilterInstance* inInstanceData, 52 | const PrGPUFilterRenderParams* inRenderParams, 53 | csSDK_int32 inIndex, 54 | PPixHand inFrame); 55 | ``` 56 | 57 | Precompute a result into preallocated uninitialized host (pinned) memory. 58 | 59 | Will only be called if `PrGPUDependency_Precompute` was returned from `GetFrameDependencies`. 60 | 61 | Precomputation may be called ahead of render time. 62 | 63 | Results will be uploaded to the GPU by the host. 64 | 65 | If `outPrecomputePixelFormat` is not custom, frames will be converted to the GPU pixel format. 66 | 67 | --- 68 | 69 | ## Render 70 | 71 | ```cpp 72 | prSuiteError (*Render)( 73 | PrGPUFilterInstance* inInstanceData, 74 | const PrGPUFilterRenderParams* inRenderParams, 75 | const PPixHand* inFrames, 76 | csSDK_size_t inFrameCount, 77 | PPixHand* outFrame); 78 | ``` 79 | 80 | Render into an allocated outFrame allocated with `PrSDKGPUDeviceSuite` or operate in place. 81 | 82 | Result must be in the same pixel format as the input. If the effect grows or shrinks the output area (e.g. rendering a drop shadow), it is allowable for the effect to allocate and return a different sized outFrame. 83 | 84 | For effects, `inFrames[0]` will always be the frame at the current time, other input frames will be in the same order as returned from `GetFrameDependencies`. For transitions `inFrames[0]` will be the incoming frame and `inFrames[1]` the outgoing frame. Transitions may not have other frame dependencies. 85 | 86 | Use the utility function `GetParam` to retrieve the parameter values at the current time. 87 | -------------------------------------------------------------------------------- /docs/exporters/structures.md: -------------------------------------------------------------------------------- 1 | # Structures 2 | 3 | | Structure | Sent with selector | 4 | | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | 5 | | [exDoExportRec](structure-descriptions.md#exdoexportrec) | [exSelExport](selector-descriptions.md#exselexport) | 6 | | [exExporterInfoRec](structure-descriptions.md#exexporterinforec) | [exSelStartup](selector-descriptions.md#exselstartup) | 7 | | [exExporterInstanceRec](structure-descriptions.md#exexporterinstancerec) | [exSelBeginInstance](selector-descriptions.md#exselbegininstance) and [exSelEndInstance](selector-descriptions.md#exselendinstance) | 8 | | [exGenerateDefaultParamRec](structure-descriptions.md#exgeneratedefaultparamrec) | [exSelGenerateDefaultParams](selector-descriptions.md#exselgeneratedefaultparams) | 9 | | [exParamButtonRec](structure-descriptions.md#exparambuttonrec) | [exSelParamButton](selector-descriptions.md#exselparambutton) | 10 | | [exParamChangedRec](structure-descriptions.md#exparamchangedrec) | [exSelValidateParamChanged](selector-descriptions.md#exselvalidateparamchanged) | 11 | | [exParamSummaryRec](structure-descriptions.md#exparamsummaryrec) | [exSelGetParamSummary](selector-descriptions.md#exselgetparamsummary) | 12 | | [exPostProcessParamsRec](structure-descriptions.md#expostprocessparamsrec) | [exSelPostProcessParams](selector-descriptions.md#exselpostprocessparams) | 13 | | [exQueryExportFileExtensionRec](structure-descriptions.md#exqueryexportfileextensionrec) | [exSelQueryExportFileExtension](selector-descriptions.md#exselqueryexportfileextension) | 14 | | [exQueryOutputFileListRec](structure-descriptions.md#exqueryoutputfilelistrec) | [exSelQueryOutputFileList](selector-descriptions.md#exselqueryoutputfilelist) | 15 | | [exQueryOutputSettingsRec](structure-descriptions.md#exqueryoutputsettingsrec) | [exSelQueryOutputSettings](selector-descriptions.md#exselqueryoutputsettings) | 16 | | [exQueryStillSequenceRec](structure-descriptions.md#exquerystillsequencerec) | [exSelQueryStillSequence](selector-descriptions.md#exselquerystillsequence) | 17 | | [exValidateOutputSettingsRec](structure-descriptions.md#exvalidateoutputsettingsrec) | [exSelValidateOutputSettings](selector-descriptions.md#exselvalidateoutputsettings) | 18 | -------------------------------------------------------------------------------- /docs/exporters/additional-details.md: -------------------------------------------------------------------------------- 1 | # Additional Details 2 | 3 | ## Multiplexer Tab Ordering 4 | 5 | If your exporter provides a Multiplexer tab like some of the built-in exporters do, you may find that it appears after the Video and Audio tab, rather than before those tabs as in the case of our exporters. The key is to use the following define as the parameter identifer for the multiplexer tab group: 6 | 7 | ```cpp 8 | #define ADBEMultiplexerTabGroup "ADBEAudienceTabGroup" 9 | ``` 10 | 11 | --- 12 | 13 | ## Creating a Non-Editable String in the Parameter UI 14 | 15 | During `exSelGenerateDefaultParams`, add a parameter with `exNewParamInfo.flags = exParamFlag_none`. 16 | 17 | Then during `exSelPostProcessParams`, call `AddConstrainedValuePair()` in the [Export Param Suite](suites.md#export-param-suite). 18 | 19 | If you only add one value pair, then the parameter will be a non-editable string. 20 | 21 | In the case of the SDK Exporter sample, it adds two, which appear as a pair of radio buttons side-by-side. 22 | 23 | --- 24 | 25 | ## Guidelines for Exporters in Premiere Elements 26 | 27 | First, make sure you are building the exporter using the right SDK. Premiere Elements 8 requires the Premiere Pro CS4 SDK. The next version of Premiere Elements will likely use the CS5 SDK. 28 | 29 | ### Exporter Preset 30 | 31 | For an exporter to show up in the Premiere Elements UI, you'll need to create and install a preset in a specific location: 32 | 33 | 1. Create a folder named "OTHERS" in [App installation folder]/sharingcenter/Presets/pc/ 34 | 2. Create a sub-folder with your name (e.g. MyCompany) under OTHERS and place the preset file (.epr) in it. The final path of the preset file should be something like [App installation folder]/ sharingcenter/Presets/pc/OTHERS/MyCompany/MyPreset.epr 35 | 3. Relaunch Premiere Elements. 36 | 4. Add a clip to the timeline 37 | 5. Goto the "Share" tab 38 | 6. Under that choose "Personal Computer" 39 | 7. You should see the "Others - 3rd Party Plugins" in the list of formats. Select this. 40 | 8. Your preset should be seen in the drop-down. 41 | 42 | ### Return Values 43 | 44 | Premiere Elements 8 uses a slightly different definition of the return values. Use the following definition instead: 45 | 46 | ```cpp 47 | enum { 48 | exportReturn_ErrNone = 0, 49 | exportReturn_Abort, 50 | exportReturn_Done, 51 | exportReturn_InternalError, 52 | exportReturn_OutputFormatAccept, 53 | exportReturn_OutputFormatDecline, 54 | exportReturn_OutOfDiskSpace, 55 | exportReturn_BufferFull, 56 | exportReturn_ErrOther, 57 | exportReturn_ErrMemory, 58 | exportReturn_ErrFileNotFound, 59 | exportReturn_ErrTooManyOpenFiles, 60 | exportReturn_ErrPermErr, 61 | exportReturn_ErrOpenErr, 62 | exportReturn_ErrInvalidDrive, 63 | exportReturn_ErrDupFile, 64 | exportReturn_ErrIo, 65 | exportReturn_ErrInUse, 66 | exportReturn_IterateExporter, 67 | exportReturn_IterateExporterDone, 68 | exportReturn_InternalErrorSilent, 69 | exportReturn_ErrCodecBadInput, 70 | exportReturn_ErrLastErrorSet, 71 | exportReturn_ErrLastWarningSet, 72 | exportReturn_ErrLastInfoSet, 73 | exportReturn_ErrExceedsMaxFormatDuration, 74 | exportReturn_VideoCodecNeedsActivation, 75 | exportReturn_AudioCodecNeedsActivation, 76 | exportReturn_IncompatibleAudioChannelType, 77 | exportReturn_Unsupported = -100 78 | }; 79 | ``` 80 | 81 | The red values are unique to Premiere Elements 8, and shifted the subsequent return values 2 values higher than their definition in the Premiere Pro SDK. 82 | -------------------------------------------------------------------------------- /docs/video-filters/additional-details.md: -------------------------------------------------------------------------------- 1 | # Additional Details 2 | 3 | ## Fields and Field Processing 4 | 5 | In an interlaced project, Premiere calls your video filter once per field. 6 | 7 | This allows video filters to have interlaced motion. `(*theData)->total` will be twice as large, each frame will be half-height, and rowbytes will double. 8 | 9 | Respect the value of rowbytes when traversing data or the output will be incorrect. 10 | 11 | --- 12 | 13 | ## Frame Caching 14 | 15 | The rendered output of video filters is stored in the host media cache. For example, when the user scrubs over a frame with a filter on it, the filter will be called to render its effect on the frame and return the buffer to Premiere. Premiere caches the returned frame, so when the user scrubs over the same frame, Premiere will return the cached frame without having to call the filter again. If the user has modified the filter settings, the clip settings, the preview quality, etc, Premiere will call the filter to render with the new settings, but will keep the previously cache frame for a while. So if the changes are reversed, Premiere may still have the cached frame to return when appropriate. 16 | 17 | If the filter should generate random, non-deterministic output, or if it changes over time without keyframes, the randomness bit must be set in the `ANIM_FilterInfo` section in the PiPL (.r file). 18 | 19 | If you set the bit to noRandomness, Premiere will only render one frame of a still image. 20 | 21 | --- 22 | 23 | ## Creating Effect Presets 24 | 25 | Effect presets appear in the Presets bin in the Effects panel, and can be applied just like Effects with specific parameter settings and keyframes. Effect presets can be created as follows: 26 | 27 | 1. Apply a filter to a clip 28 | 2. Set the parameters of the filter, adding keyframes if desired 29 | 3. Right-click on the filter name in the Effect Controls panel, and select "Save Preset…" 30 | 4. Create preset bins if desired by right-clicking in the Effects panel and choosing "New Presets Bin" 31 | 5. Organize the presets in the preset folders 32 | 6. Select the bins and/or presets you wish to export, right-click, and choose "Export Preset" 33 | 34 | On Windows, newly created presets are saved in the hidden Application Data folder of the user's Documents and Settings (e.g. `C:/Documents and Settings/[user]/Application Data/Adobe Premiere Pro/[version]/Effect Presets and Custom Items.prfpset`). On MacOS, they are in the user folder, at `~/Library/Application Support/Adobe/Premiere Pro/[version]/Effect Presets and Custom Items.prfpset.` 35 | 36 | Effect Presets should be installed as described in the section, "Plugin Installation". Once they are installed in that folder, they will be read-only, and the user will not be able to move them to a different folder or change their names. User-created presets will be modifiable. 37 | 38 | --- 39 | 40 | ## Premiere Elements and Effect Thumbnail Previews 41 | 42 | Premiere Elements (but not Premiere Pro) displays visual icons for each effect. You will need to provide icons for your effects, or else an empty black icon will be shown for your effects, or even worse behavior in Premiere Elements 8. The icons are 60x45 PNG files, and are placed here: 43 | 44 | `/[Program Files]/Adobe/Adobe Premiere Elements [version]/Plugins/Common/Effect/Previews/` 45 | 46 | The filename should be the match name of the effect, which you specify in the PiPL, prefixed with "PR." So if the match name was "MatchName", then the filename should be "PR.MatchName.png" 47 | -------------------------------------------------------------------------------- /docs/exporters/selector-table.md: -------------------------------------------------------------------------------- 1 | # Selector Table 2 | 3 | This table summarizes the various selector commands an exporter can receive. 4 | 5 | | Selector | param1 | param2 | 6 | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------ | 7 | | [exSelStartup](selector-descriptions.md#exselstartup) | [exExporterInfoRec*](structure-descriptions.md#exexporterinforec) | unused | 8 | | [exSelBeginInstance](selector-descriptions.md#exselbegininstance) | [exExporterInstanceRec*](structure-descriptions.md#exexporterinstancerec) | unused | 9 | | [exSelGenerateDefaultParams](selector-descriptions.md#exselgeneratedefaultparams) | [exGenerateDefaultParamRec*](structure-descriptions.md#exgeneratedefaultparamrec) | unused | 10 | | [exSelPostProcessParams](selector-descriptions.md#exselpostprocessparams) | [exPostProcessParamsRec*](structure-descriptions.md#expostprocessparamsrec) | unused | 11 | | [exSelValidateParamChanged](selector-descriptions.md#exselvalidateparamchanged) | [exParamChangedRec*](structure-descriptions.md#exparamchangedrec) | unused | 12 | | [exSelGetParamSummary](selector-descriptions.md#exselgetparamsummary) | [exParamSummaryRec*](structure-descriptions.md#exparamsummaryrec) | unused | 13 | | [exSelParamButton](selector-descriptions.md#exselparambutton) | [exParamButtonRec*](structure-descriptions.md#exparambuttonrec) | unused | 14 | | [exSelExport](selector-descriptions.md#exselexport) | [exDoExportRec*](structure-descriptions.md#exdoexportrec) | unused | 15 | | [exSelQueryExportFileExtension](selector-descriptions.md#exselqueryexportfileextension) | [exQueryExportFileExtensionRec*](structure-descriptions.md#exqueryexportfileextensionrec) | unused | 16 | | [exSelQueryOutputFileList](selector-descriptions.md#exselqueryoutputfilelist) | [exQueryOutputFileListRec*](structure-descriptions.md#exqueryoutputfilelistrec) | unused | 17 | | [exSelQueryStillSequence](selector-descriptions.md#exselquerystillsequence) | [exQueryStillSequenceRec*](structure-descriptions.md#exquerystillsequencerec) | unused | 18 | | [exSelQueryOutputSettings](selector-descriptions.md#exselqueryoutputsettings) | [exQueryOutputSettingsRec*](structure-descriptions.md#exqueryoutputsettingsrec) | unused | 19 | | [exSelValidateOutputSettings](selector-descriptions.md#exselvalidateoutputsettings) | [exValidateOutputSettingsRec*](structure-descriptions.md#exvalidateoutputsettingsrec) | unused | 20 | | [exSelExport2](selector-descriptions.md#exselexport2) | [exDoExportRec2*](structure-descriptions.md#exdoexportrec2) | unused | 21 | | [exSelQueryExportColorSpace](selector-descriptions.md#exselqueryexportcolorspace) | [exQueryExportColorSpaceRec*](structure-descriptions.md#exqueryexportcolorspacerec) | unused | 22 | | [exSelShutdown](selector-descriptions.md#exselshutdown) | [exExporterInfoRec*](structure-descriptions.md#exexporterinforec) | unused | 23 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/suites.md: -------------------------------------------------------------------------------- 1 | # Suites 2 | 3 | For information on how to acquire and manage suites, see [SweetPea Suites](../universals/sweetpea-suites.md). 4 | 5 | --- 6 | 7 | ## GPU Device Suite 8 | 9 | This suite provides info on any GPU devices available. For example, GetDeviceInfo() allows an effect/transition to see if the device supports OpenCL or CUDA. 10 | 11 | Use this suite to get exclusive access to a device using AcquireExclusiveDeviceAccess and ReleaseExclusiveDeviceAccess. If needed, you can reconcile devices using the outDeviceHandle passed back from GetDeviceInfo(). 12 | 13 | Device memory should ideally be allocated through this suite. In some cases you may find it more efficient to use a texture / image object as the source. With CUDA, you can bind a texture reference to an existing linear buffer. With OpenCL, you can create an image object from an existing 2D buffer object using image_2d_from_buffer. Temporary allocations are also fine but may be rather slow. 14 | 15 | --- 16 | 17 | ## Opaque Effect Data Suite 18 | 19 | This suite provides effects a way to share unflattened sequence data between instances of the same effect on a track item. The data is opaque to the host and effects are responsible for maintaining thread safety of the shared data. The host provides reference-counting that the effect can use to manage the lifetime of the shared data. Here's an overview of how this suite should be used: 20 | 21 | When the effect is applied, in `PF_Cmd_SEQUENCE_SETUP`, the effect plugin allocates and initializes the sequence data in PF_OutData->out_data. Then it calls 22 | 23 | AcquireOpaqueEffectData(). The opaque effect data does not yet exist, so the plugin allocates it, and calls RegisterOpaqueEffectData, and then copies over the data from the sequence data. So both sequence data and opaque effect data are allocated. 24 | 25 | Then `PF_Cmd_SEQUENCE_RESETUP` is called (multiple times) for clones of the effect used for rendering. The effect instance knows it's a clone because the PF_InData->sequence_data is NULL (there is a special case if the effect has Opaque Effect Data - in that case, its render clones will receive `PF_Cmd_SEQUENCE_RESETUP` with a NULL sequence_data pointer). It then calls AcquireOpaqueEffectData(). As a render clone, it relies on this opaque effect data, rather than sequence data, and does not try to copy the sequence data to opaque effect data. 26 | 27 | When, on the other hand, `SEQUENCE_RESETUP` is called with valid sequence_data in PF_InData, this is not a render clone. The plugin unflattens this sequence data. It then calls AcquireOpaqueEffectData(), and if the opaque effect data does not yet exist (i.e. when reopening a saved project), the plugin allocates it, and calls RegisterOpaqueEffectData. It then copies the sequence data to opaque effect data. 28 | 29 | On `SEQUENCE_FLATTEN`, the plugin takes the unflattened data, flattens it, and disposes of the un-flat data. 30 | 31 | When `SEQUENCE_SETDOWN` is called (it may be called multiple times to dispose of render clones), ReleaseOpaqueEffectData() is called. 32 | 33 | ### instanceID 34 | 35 | The [Opaque Effect Data Suite](#opaque-effect-data-suite) functions need the instanceID of the effect. For the software entry point, you can obtain this using GetFilterInstanceID() in PF_UtilitySuite, defined in PrSDKAESupport.h. For the GPU Render entry point, you can use the following code: csSDK_uint32 instanceID; 36 | 37 | ```cpp 38 | GetProperty( kVideoSegmentProperty_Effect_RuntimeInstanceID, instanceID); 39 | ``` 40 | 41 | …where GetProperty() is defined in PrGPUFilterModule.h, and the `kVideoSegmentProperty_` IDs are defined in PrSDKVideoSegmentProperties.h. 42 | -------------------------------------------------------------------------------- /docs/intro/load-em-up.md: -------------------------------------------------------------------------------- 1 | # Load Em Up 2 | 3 | ## Plugin Caching 4 | 5 | On its first launch, Premiere Pro loads all the plugins, reads the [plugin Property Lists (PiPL) Resource](../resources/pipl-resource.md), and sends any startup selectors to determine the plugins' capabilities. To speed up future application launches, it saves some of these capabilities in what we call the plugin cache (the registry on Windows, a Property List file on macOS). 6 | 7 | The next time the application is launched, the cached data is used wherever possible, rather than loading all the plugins on startup. Using this changed data will make the application launch faster, but for a small set of plugins that need to be initialized every time, it may be undesirable. These include plugins that need to get run-time information that might change in between app launches (i.e. installed codec lists), and plugins that check for hardware and need to be able to fail. So we give your plugin control final say over whether or not it is reloaded each time. 8 | 9 | By default, importers, recorders, and exporters are not cached. Exporters can be cached by setting exExporterInfoRec.isCacheable to non-zero during *exSelStartup*. Importers and recorders can be cached by returning `*IsCacheable` instead of `*NoError` (e.g. for importers, imIsCacheable instead of imNoError) on the startup selector. 10 | 11 | By default, legacy video filters and device controllers are cached by default. To specify that legacy video filters must be reloaded each time, rather than cached, Premiere filters should respond to *fsCacheOnLoad*. 12 | 13 | --- 14 | 15 | ## Resolving Plugin Loading Problems 16 | 17 | There are various tools to help in the development process. 18 | 19 | On Windows only, you can force Premiere to reload all the plugins by holding down shift on startup. The plugin cache on macOS may be deleted manually from the user folder, at `~/Library/Preferences/com.Adobe.Premiere Pro [version].plist.` 20 | 21 | For plugin loading issues, you may first check one of the plugin loading logs. 22 | 23 | On Windows: `[user folder]\AppData\Roaming\Adobe\Premiere Pro\[version number]\Plugin Loading.log` 24 | 25 | On macOS, this is: `~/Library/Application Support/Adobe/Premiere Pro/[version number]/Plugin Loading.log` 26 | 27 | Your plugin will be listed by path and filename, and the log will contain details on what happened during the plugin loading process. Starting in CC 2017, it now logs any error codes returned from an effect on *PF_Cmd_GLOBAL_SETUP*. 28 | 29 | If the log says a plugin has been marked as Ignore, the most common culprit is a library dependency that could not be loaded. If your plugin uses some image processing or proprietary code library, is it installed on the system, and in the right place? On Windows, a tool such as Dependency Walker (depends.exe) is helpful to check a plugin's dependencies. 30 | 31 | --- 32 | 33 | ## Loading unsigned plugins 34 | 35 | MacOS versions 15+ prevent the loading of unsigned plugins. You can avoid this difficulty by adding ad-hoc signing as a custom build step. 36 | 37 | `codesign --force --deep --sign - /path/to/plugin.dylib` 38 | 39 | Note: Yes, that trailing '-' after '--sign' is important. 40 | 41 | --- 42 | 43 | ## Library Linkage 44 | 45 | On Windows, we strongly recommend dynamically linking to libraries, rather than static linking. In Visual Studio, the runtime library linkage setting is in C/C++ > Code Generation > Runtime Library. 46 | 47 | We ask developers to compile with the /MD flag (or /MDd for debug builds), and not with the /MT flag. 48 | 49 | Failure to do so can contribute to the problem where the Premiere Pro process can run out of fiber-local storage slots, and subsequent plugins fail to load. 50 | 51 | --- 52 | 53 | ## No Shortcuts 54 | 55 | The Premiere Pro plugin loader does not follow Windows shortcuts. Although it does follow macOS symbolic links, we recommend against using symbolic links in the plugins folder, since the plugin loader checks the timestamp of the symbolic link rather than the timestamp of the plugin pointed to. 56 | 57 | Explanation: If you use a symbolic link and the plugin fails to load once (for example, if the plugin pointed to isn't there) it will be marked to ignore when Premiere launches. Even if the plugin is restored to the proper location, the plugin loader will check the modification time of 58 | 59 | the symbolic link, rather than the plugin pointed to, and continue to ignore the plugin until the modification date of the symbolic link is updated. So plugins should be placed directly in a plugins folder or subfolder. 60 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/gpu-effects-transitions.md: -------------------------------------------------------------------------------- 1 | # GPU Effects & Transitions 2 | 3 | This chapter describes the additional capabilities available to effects and transitions for GPU interoperability with Premiere Pro. The GPU extensions allow these plugins to have full access to GPU-resident frames without readback to system memory, when using the Mercury Playback Engine in a GPU-accelerated mode. Effects and transitions can also optionally tell the host that they support real-time processing, so that they will not be flagged as non-realtime. 4 | 5 | The GPU extensions work on top of effects and transitions built using the After Effects SDK. The extensions are designed to supplement a regular software effect or transition, which defines the software rendering path, parameters, custom UI drawing, and other standard interaction. The GPU effect exists as a new entry point for rendering using the GPU if possible. The software render path will be used otherwise. 6 | 7 | --- 8 | 9 | ## System Requirements 10 | 11 | The system requirements for developing GPU effects & transitions are higher than developing other plugins. You'll need a video card that supports Mercury Playback Engine GPU acceleration. Make sure your video card supports the type of video acceleration you are developing, on the platform you are developing on. See this page for the latest supported video cards: [https://helpx.adobe.com/premiere-pro/system-requirements.html](https://helpx.adobe.com/premiere-pro/system-requirements.html) 12 | 13 | The CUDA SDK is also needed for CUDA rendering development. 14 | 15 | --- 16 | 17 | ## Compilation notes 18 | 19 | ### CUDA 20 | 21 | To compile GPU effects in Premiere SDK, we highly recommend using CUDA SDK 11.8. 22 | 23 | Caution: GPU Effects built using CUDA SDK 11.8 will not work with NVIDIA Kepler generation cards. The minimum CUDA Compute Capability has been increased to sm_50. 24 | 25 | ### CUDA Runtime API vs. Driver API 26 | 27 | 1. Utilize CUDA Driver API 28 | For best compatibility, we highly recommend utilizing CUDA Driver API only. Unlike the runtime API, the driver API is directly backwards compatible with future drivers. Please note that the CUDA Runtime API is built to handle/automate some of the housekeeping that is exposed and needs to be handled in the Driver APIs, so there might be some new steps/code you would need to learn and implement for migrating from Runtime API to Driver API. 29 | 30 | 2. Statically Link to CUDA Runtime 31 | If you must stick to CUDA Runtime API, we recommend you statically link to the CUDA Runtime. That's an alternative way for leveraging the backwards compatibility of the driver into the future. This can be done by linking cudart_static.lib. 32 | 33 | 3. Dynamically Link to CUDA Runtime 34 | This also works but would be prone to compatibility issues. A compatible CUDA Runtime DLL needs to be available on users' systems so that driver can understand and be backward compatible. Currently Premiere Pro ships a copy of CUDA Runtime DLL of our recommended CUDA SDK version. This may change in future. If you must dynamically link to CUDA Runtime, we recommend you ship a copy of the CUDA Runtime DLL with your plugin and leverage dlopen/LoadLibrary to explicitly load the desired runtimes. For more details, see the CUDA Compatibility section of NVIDIA's GPU Management and Deployment guide: [https://docs.nvidia.com/deploy/cuda-compatibility/](https://docs.nvidia.com/deploy/cuda-compatibility/) 35 | 36 | --- 37 | 38 | ## DirectX 39 | 40 | We would like to announce that we have been working on introducing support for DirectX 12 in our rendering pipeline. We will soon be sharing unlock instructions to enable DirectX in your application. 41 | 42 | ### Why? 43 | 44 | - Performance - DirectX 12 is a thin wrapper over the hardware which would provide us with more control than OpenCL/CUDA over the execution of our shaders. This translates to a higher ceiling for performance 45 | - Stability/Error Handling - DirectX 12 supports TDR detection and recovery which can help us recover from hardware problems. It is actively supported by Microsoft i.e., proactive fixes for bugs in drivers 46 | - Interoperability - Seamless interoperability with our display module which already uses DirectX12 47 | 48 | ### Direction 49 | 50 | Adding a new rendering engine to Premiere is a massive undertaking. Although we have made significant progress, it is still under development and will have an update for you soon. 51 | 52 | ### Feedback & Support 53 | 54 | We will be happy to receive any thoughts regarding DirectX or answer any questions. I am reachable at, [pusingha@adobe.com](mailto:pusingha@adobe.com) or you can post them on [ae_api_nda@adobe.com](mailto:ae_api_nda@adobe.com) 55 | -------------------------------------------------------------------------------- /docs/_global/hooks/merge_inherited_config.py: -------------------------------------------------------------------------------- 1 | # Handles merging mkdocs config in a way the native inheritance feature doesn't quite cover 2 | # 3 | # This relies on a key in "extra.overrides" 4 | # Valid keys are `custom_dir: str` and `hooks: [-path/to.py, -path/to.py]`, e.g. 5 | # 6 | # ```yml 7 | # extra: 8 | # overrides: 9 | # custom_dir: overrides 10 | # extra_css: 11 | # - docs/_global/css/global.css 12 | # - docs/_global/css/global-syntax-highlight.css 13 | # extra_javascript: 14 | # - docs/_global/js/global.js 15 | # hooks: 16 | # - hooks/local_override.py 17 | # - hooks/local_override2.py 18 | # not_in_nav: 19 | # - gitignore_style/path/to/exclude 20 | # theme_features: 21 | # - theme.feature1 22 | # - theme.feature2 23 | # ``` 24 | 25 | import os 26 | 27 | from pathspec.gitignore import GitIgnoreSpec 28 | 29 | import mkdocs 30 | from mkdocs.config.defaults import MkDocsConfig 31 | from mkdocs.config.config_options import (File, FilesystemObject, Hooks, ListOfItems, PathSpec) 32 | from mkdocs.structure.files import (File as FileStructure, Files) 33 | 34 | # Load any local files into mkdocs 35 | def append_local_files(files: Files, config: MkDocsConfig, local_files: list[str]): 36 | for local_file_path in local_files: 37 | local_file = FileStructure( 38 | path= local_file_path, 39 | src_dir=config["docs_dir"] + "/../", 40 | dest_dir=config["site_dir"], 41 | use_directory_urls=False, 42 | ) 43 | 44 | files.append(local_file) 45 | 46 | # Load any override hooks 47 | def merge_local_hooks(config: MkDocsConfig, hooks: list[str]): 48 | try: 49 | paths = ListOfItems(File(exists=True)).validate(hooks) 50 | except Exception as e: 51 | raise e 52 | 53 | for name, path in zip(hooks, paths): 54 | config.plugins[name] = Hooks._load_hook(mkdocs, name, path) 55 | 56 | # Handle multiple "not in nav" entries 57 | # These are of a pathspec.gitignore.GitIgnoreSpec format and need to be converted to a multiline string 58 | def merge_local_not_in_nav(config: MkDocsConfig, not_in_nav: list[GitIgnoreSpec]): 59 | nav_str = "\n".join(not_in_nav) 60 | config["not_in_nav"] += PathSpec().run_validation(nav_str) 61 | 62 | # Add additional theme_override folder 63 | def merge_local_theme_override(config: MkDocsConfig, custom_dir: str): 64 | try: 65 | local_override_path = FilesystemObject(exists=True).validate(custom_dir) 66 | except Exception as e: 67 | raise e 68 | 69 | config.theme.dirs.insert(1, local_override_path) 70 | 71 | # Load any override theme features 72 | def merge_local_theme_features(config: MkDocsConfig, theme_features: list[str]): 73 | for local_feature in theme_features: 74 | config.theme["features"].append(local_feature) 75 | 76 | 77 | 78 | ##### MkDocs Event Hooks 79 | 80 | def on_files(files: Files, config: MkDocsConfig): 81 | if "overrides" in config.extra: 82 | extra_overrides = config.extra["overrides"] 83 | 84 | if "extra_css" in extra_overrides: 85 | extra_css = extra_overrides["extra_css"] 86 | append_local_files(files, config, extra_css) 87 | 88 | if "extra_javascript" in extra_overrides: 89 | extra_javascript = extra_overrides["extra_javascript"] 90 | append_local_files(files, config, extra_javascript) 91 | 92 | def on_config(config: MkDocsConfig): 93 | if "overrides" in config.extra: 94 | extra_overrides = config.extra["overrides"] 95 | 96 | # Keep Hooks first 97 | if "hooks" in extra_overrides: 98 | hooks = extra_overrides["hooks"] 99 | merge_local_hooks(config, hooks) 100 | 101 | if "custom_dir" in extra_overrides: 102 | custom_dir = extra_overrides["custom_dir"] 103 | merge_local_theme_override(config, custom_dir) 104 | 105 | if "extra_css" in extra_overrides: 106 | extra_css = extra_overrides["extra_css"] 107 | config.extra_css.extend(extra_css) 108 | 109 | if "extra_javascript" in extra_overrides: 110 | extra_javascript = extra_overrides["extra_javascript"] 111 | config.extra_javascript.extend(extra_javascript) 112 | 113 | if "not_in_nav" in extra_overrides: 114 | not_in_nav = extra_overrides["not_in_nav"] 115 | merge_local_not_in_nav(config, not_in_nav) 116 | 117 | if "theme_features" in extra_overrides: 118 | theme_features = extra_overrides["theme_features"] 119 | merge_local_theme_features(config, theme_features) 120 | -------------------------------------------------------------------------------- /docs/video-filters/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | Begin with one of the two video filter sample projects, progressively replacing its functionality with your own. 4 | 5 | --- 6 | 7 | ## Resources 8 | 9 | Filter plugins can use PiPL resources to define their behaviors and supported properties. 10 | 11 | To provide any parameters in the Effect Controls panel, they must be defined in the PiPL in ANIM_ParamAtom sections, as demonstrated in the example below. 12 | 13 | The 'no UI' UI type is for non-keyframeable parameters. After making changes to the PiPL, rebuild the plugin each time, so that the PiPL will be recompiled. 14 | 15 | ### A Filter PiPL Example 16 | 17 | ```cpp 18 | #include "PrSDKPiPLVer.h" 19 | #ifndef PRWIN_ENV 20 | #include "PrSDKPiPL.r" 21 | #endif 22 | 23 | // The following two strings should be localized 24 | #define plugInName "Cool Video Filter" 25 | #define plugInCategory "SDK Filters" 26 | 27 | // This name should not be localized or updated 28 | #define plugInMatchName "SDK Cool Filter" 29 | 30 | resource 'PiPL' (16000) { 31 | { 32 | // The plugin type 33 | Kind {PrEffect}, 34 | 35 | // The plugin name as it will appear to the user 36 | Name {plugInName}, 37 | 38 | // The internal name of this plugin 39 | AE_Effect_Match_Name {plugInMatchName}, 40 | 41 | // The folder containing the plugin in the Effects Panel 42 | Category {plugInCategory}, 43 | 44 | // The version of the PiPL resource definition 45 | AE_PiPL_Version {PiPLVerMajor, PiPLVerMinor}, 46 | 47 | // The ANIM properties describe the filter parameters, and also how the data is stored in the project file. There is one ANIM_FilterInfo property followed by n ANIM_ParamAtoms 48 | ANIM_FilterInfo { 49 | 0, 50 | #ifdef PiPLVer2p3 51 | 52 | // Non-square pixel aspect ratio supported 53 | notUnityPixelAspectRatio, 54 | anyPixelAspectRatio, 55 | reserved4False, 56 | reserved3False, 57 | reserved2False, 58 | 59 | #endif 60 | }, 61 | 62 | reserved1False, // These flags are for use by After Effects 63 | reserved0False, // Not used by Premiere 64 | driveMe, // Not used by Premiere 65 | needsDialog, // Not used by Premiere 66 | paramsNotPointer, // Not used by Premiere 67 | paramsNotHandle, // Not used by Premiere 68 | paramsNotMacHandle, // Not used by Premiere 69 | dialogNotInRender, // Not used by Premiere 70 | paramsNotInGlobals, // Not used by Premiere 71 | bgAnimatable, // Not used by Premiere 72 | fgAnimatable, // Not used by Premiere 73 | geometric, // Not used by Premiere 74 | noRandomness, // Not used by Premiere 75 | 76 | // Put the number of parameters here 77 | 2, 78 | 79 | plugInMatchName 80 | 81 | // There is one ANIM_ParamAtom for each parameter 82 | ANIM_ParamAtom { 83 | // This is the first property - Zero based count 84 | 0, 85 | 86 | // The name to appear for the control 87 | "Level", 88 | 89 | // Parameter number goes here - One based count 90 | 1, 91 | 92 | // Put the data type here 93 | ANIM_DT_SHORT, 94 | 95 | // UI control type 96 | ANIM_UI_SLIDER, 97 | 0x0, 98 | 0x0, // valid_min (0.0) 99 | 0x405fc000, 100 | 0x0, // valid_max (127.0) 101 | 0x0, 102 | 0x0, // ui_min (0.0) 103 | 0x40590000, 104 | 0x0, // ui_max (100.0) 105 | 106 | #if PiPLVer2p3 107 | // New - Scale/dontScale UI Range if user modifies 108 | dontScaleUIRange, 109 | #endif 110 | }, 111 | 112 | // Set/don't set this if the param should be animated 113 | animateParam, 114 | dontRestrictBounds, // Not used by Premiere 115 | spaceIsAbsolute, // Not used by Premiere 116 | resIndependent, // Not used by Premiere 117 | 118 | // Bytes size of the param data 119 | 2 120 | 121 | ANIM_ParamAtom { 122 | 1, 123 | "Target Color", 2, 124 | 125 | // Put the data type here 126 | ANIM_DT_COLOR_RGB, 127 | 128 | // UI control type 129 | ANIM_UI_COLOR_RGB, 130 | 0x0, 131 | 0x0, 132 | 0x0, 133 | 0x0, 134 | 0x0, 135 | 0x0, 136 | 0x0, 137 | 0x0, 138 | 139 | #ifdef PiPLVer2p3 140 | dontScaleUIRange, 141 | #endif 142 | 143 | // Set/don't set this if the param should be animated 144 | animateParam, 145 | dontRestrictBounds, 146 | spaceIsAbsolute, 147 | resIndependent, 148 | 149 | // Bytes size of the param data 150 | 4 151 | }, 152 | } 153 | }; 154 | ``` 155 | 156 | --- 157 | 158 | ## Entry Point 159 | 160 | ```cpp 161 | short xFilter ( 162 | short selector, 163 | VideoHandle theData) 164 | ``` 165 | 166 | - `selector` is the action Premiere wants the video filter to perform. 167 | - `EffectHandle` provides source and destination buffers, and other useful information. 168 | 169 | Return `fsNoErr` if successful, or an appropriate return code. 170 | -------------------------------------------------------------------------------- /docs/video-filters/selector-descriptions.md: -------------------------------------------------------------------------------- 1 | # Selector Descriptions 2 | 3 | ## fsInitSpec 4 | 5 | Responding to this selector is optional. This selector is sent when the filter is applied to a clip and the plugin is called for the first time. This call can be used to initialize the plugin parameters with default values in order to achieve an initial "silent setup", in which `fsSetup` is skipped when the filter is applied to a clip, to avoid popping the modal dialog that may be needed in `fsSetup`. 6 | 7 | Allocate and pass back a handle to a structure containing the parameter values in specsHandle. The filter is given the total duration (in samples), and number of the first sample in the source buffer. 8 | 9 | --- 10 | 11 | ## fsHasSetupDialog 12 | 13 | New for Premiere Pro CS3. Optional. Specify whether or not the filter has a setup dialog, by `returning` `fsHasNoSetupDialog` or `fsNoErr`. 14 | 15 | --- 16 | 17 | ## fsSetup 18 | 19 | Optional. Sent when the filter is applied, if `fsInitSpec` doesn't allocate a valid specsHandle. Also sent when the user clicks on the setup link in the Effect Controls Panel. The filter can optionally display a (platform-dependent) modal dialog to get new parameter values from the user. First, check `VideoHandle.specsHandle`. If NULL, the plugin is being called for the first time. 20 | 21 | Initialize the parameters to their default values. If non-NULL, load the parameter values from specsHandle. Now use the parameter values to display a modal setup dialog to get new values. Return a handle to a structure containing the parameter values in specsHandle. 22 | 23 | In order to properly store parameter values between calls to the plugin, describe the structure of your specsHandle data in your PiPL's ANIM properties. Premiere interpolates animatable parameter values as appropriate before sending `fsExecute`. 24 | 25 | The filter is given the total duration in samples and the sample number of the first sample in the source buffer. 26 | 27 | During `fsSetup`, the frames passed to `VideoRecord.source` will almost always be 320x240. The exception is if the plugin is receiving the `fsSetup` selector when the effect is initially applied, in which case it will receive a full height frame, with the width adjusted to make the frame square pixel aspect ratio. For example, a filter applied in a 1440x1080 HDV sequence will receive a full 1920x1080 buffer. The frame is the layer the filter is applied to at the current time indicator. If the CTI is not on the clip the filter is applied to, the frame is transparent black. 28 | 29 | If the filter has a setup dialog, the VFilterCallbackProcPtr should be used to get source frames for previews. `getPreviewFrameEx` can be used to get rendered frames, although if this call is used, the video filter should be ready to be called reentrantly with `fsExecute`. 30 | 31 | --- 32 | 33 | ## fsExecute 34 | 35 | This is really the only required selector for a video filter, and it's where the rendering happens. Take the input frame in `VideoHandle.source`, render the effect and return the frame to Premiere in `VideoHandle.destination`. The specsHandle contains your parameter settings (already interpolated if animatable). You can store a handle to any additional non-parameter data in `VideoHandle.InstanceData`. If you do so, deallocate the handle in response to `fsDisposeData`, or your plugin will leak memory. 36 | 37 | The video your filter receives may be interlaced, in the field order determined by the project settings. If interlaced, your plugin will be called twice for each frame of video, and each PPix will be half the frame height. 38 | 39 | --- 40 | 41 | ## fsDisposeData 42 | 43 | Optional. Called when the project closes. Dispose of any instance data created during `fsExecute`. See `VideoHandle->InstanceData`. 44 | 45 | --- 46 | 47 | ## fsCanHandlePAR 48 | 49 | Optional. Indicate how your filter wants to handle pixel aspect ratio by returning a combination of the following flags. 50 | 51 | This selector is only sent if several conditions are met. 52 | 53 | The pixel aspect ratio of the clip to which the filter is applied must be known, and not be square (1.0). 54 | 55 | The clip must not be a solid color. 56 | 57 | The PiPL bits `anyPixelAspectRatio` and `unityPixelAspectRatio` must not be set. 58 | 59 | | Flag | Description | 60 | | ------------------------- | --------------------------------------------------------------------------------- | 61 | | `prEffectCanHandlePAR` | Premiere should not make any adjustment to the source image to compensate for PAR | 62 | | `prEffectUnityPARSetup` | Premiere should render the source image to square pixels during `fsSetup` | 63 | | `prEffectUnityPARExecute` | Premiere should render the source image to square pixels during `fsExecute` | 64 | 65 | --- 66 | 67 | ## fsGetPixelFormatsSupported 68 | 69 | Optional. 70 | 71 | Gets pixel formats supported. 72 | 73 | Called iteratively until all formats have been given. 74 | 75 | Set `(*theData)->pixelFormatSupported` to a supported pixel format, and return `fsNoErr`. 76 | 77 | When all formats have been described, return `fsBadFormatIndex`. 78 | 79 | See the field-aware video filter sample for an example. 80 | 81 | --- 82 | 83 | ## fsCacheOnLoad 84 | 85 | Optional. Return `fsDoNotCacheOnLoad` to disable plugin caching for this filter. 86 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ## Setting up the Sample Projects 4 | 5 | If you are developing an effect, begin with one of the two GPU effect sample projects, progressively replacing its functionality with your own. Refer to [Introduction](../index.md) for general instructions on how to build the SDK projects. 6 | 7 | In addition to those general instructions, the sample project is also dependent on the After Effects plugin SDK. On Windows, create an environment variable pointing to it named AE_SDK_BASE_PATH, so that the compiler will find the AE headers that the project includes. On macOS, in *XCode > Preferences > Locations > Custom Paths*, specify AE_SDK_BASE_PATH to be the root folder of the AE plugin SDK you have downloaded and unzipped. 8 | 9 | The samples also use Boost, which may be downloaded at boost.org. Download that, and create a variable named BOOST_BASE_PATH just as you did with AE_SDK_BASE_PATH above. 10 | 11 | Finally, install Python (version 3.6 or greater), if you do not have it already. It may be downloaded at python.org. The sample projects use this as part of the custom build steps. 12 | 13 | Depending on whether your effect will use CUDA, you'll need to download the CUDA SDK. On Windows, create an environment variable pointing to it named CUDA_SDK_BASE_PATH, so that the linker will find the right libraries. 14 | 15 | --- 16 | 17 | ## Querying for Parameters and other Attributes of a Effect or Transition 18 | 19 | You'll notice that PrGPUFilterRenderParams has some attributes about an effect or transition, but many things, such as the parameters or duration of the clip to which the plugin is applied, are not found in that structure. These attributes will need to be queried using the GetParam() and GetProperty() helper functions in PrGPUFilterModule.h. For example: 20 | 21 | ```cpp 22 | GetProperty(kVideoSegmentProperty_Effect_EffectDuration, duration); 23 | GetProperty(kVideoSegmentProperty_Transition_TransitionDuration, duration); 24 | ``` 25 | 26 | --- 27 | 28 | ## Lifetime of a GPU Effect / Transition 29 | 30 | A new GPU effect instance is created when an effect/transition is applied in the timeline, or when an effect parameter is changed. When rendering a series of frames it won't needlessly be recreated. The [Opaque Effect Data Suite](suites.md#opaque-effect-data-suite) should be used to share unflattened sequence data between instances of the same effect on a track item. 31 | 32 | --- 33 | 34 | ## Fallback to Software Rendering 35 | 36 | When a new GPU effect instance is created, the instance has the option of opting-in or out of providing GPU rendering. The GPU effect should be reasonably sure it has sufficient resources to complete the render if it opts-in, because there is no API support to fall back to software rendering in the middle of a render. 37 | 38 | Calling GetDeviceInfo() in the [GPU Device Suite](suites.md#gpu-device-suite), and checking `outDeviceInfo.outMeetsMinimumRequirementsForAcceleration`, you can see if supports the minimum system requirements for acceleration. Do not proceed with 39 | 40 | AcquireExclusiveDeviceAccess(), if the minimum requirements are not met. 41 | 42 | In emergency situations, when there is not enough GPU memory available to complete a render, an effect may call PurgeDeviceMemory in the [GPU Device Suite](suites.md#gpu-device-suite) to free up memory not initially available. This will impact performance, and should be used only if absolutely necessary. 43 | 44 | --- 45 | 46 | ## OpenGL Interoperability 47 | 48 | If you want, you have the ability to transfer frames from CUDA to OpenGL (though not always efficiently). 49 | 50 | For CUDA interoperability with OpenGL: 51 | 52 | ### CUDA -> OpenGL 53 | 54 | - Create an OpenGL buffer 55 | - map it into CUDA with `cuGraphicsMapResources` 56 | - get the mapped address with `cuGraphicsResourceGetMappedPointer` 57 | - copy from the CUDA address to the mapped address with `cuMemcpyDtoDAsync` 58 | - unmap with `cuGraphicsUnmapResources` 59 | 60 | ### OpenGL -> CUDA 61 | 62 | - Map the OpenGL buffer into CUDA with `cuGraphicsMapResources` 63 | - get the mapped address with `cuGraphicsResourceGetMappedPointer` 64 | - copy from the mapped address to CUDA with `cuMemcpyDtoDAsync` 65 | - unmap with `cuGraphicsUnmapResources` 66 | 67 | !!! note 68 | On the Mac there is no real OpenGL/CUDA interoperability, and these calls will go through system memory. 69 | 70 | --- 71 | 72 | ## Entry Point 73 | 74 | The GPU entry point function will only be called if the current project is using GPU acceleration. Otherwise, the normal entry point function will be called as described in the After Effects SDK, or [GPU Effects & Transitions](gpu-effects-transitions.md) or [Video Filters](../video-filters/video-filters.md) in this SDK Guide. 75 | 76 | Make sure GPU acceleration is activated in File > Project Settings > General > Video Rendering and Playback > Renderer. If a GPU option is not available, then you will need to install a suitable video card in your system. 77 | 78 | ```cpp 79 | prSuiteError xGPUFilterEntry ( 80 | csSDK_uint32 inHostInterfaceVersion, 81 | csSDK_int32* ioIndex, 82 | prBool inStartup, 83 | piSuitesPtr piSuites, 84 | PrGPUFilter* outFilter, 85 | PrGPUFilterInfo* outFilterInfo) 86 | ``` 87 | 88 | If `inStartup` is non-zero, the effect/transition should startup and initialize the functions needed to implement PrGPUFilter, as well as the info in PrGPUFilterInfo. 89 | 90 | If `inStartup` is false, then the effect/transition should shutdown, unloading any resources it loaded on startup. 91 | 92 | As of CC, inHostInterfaceVersion is `PrSDKGPUFilterInterfaceVersion1 == 1` 93 | 94 | If a single plugin supports multiple effects, increment ioIndex to the next value before returning, in order to be called again to describe the next effect. 95 | -------------------------------------------------------------------------------- /docs/exporters/whats-new.md: -------------------------------------------------------------------------------- 1 | # Whats New 2 | 3 | ## What's New in CC (7.0) 4 | 5 | A new Captions tab has been added to the Export Settings, for Closed Captioning export. For all formats, a sidecar file containing the captions can be exported. 6 | 7 | To learn how exporters can optionally embed Closed Captioning directly in the output file, see [Closed Captioning](getting-started.md#closed-captioning). 8 | 9 | Two new selectors have been added to GetExportSourceInfo in the [Export Info Suite](suites.md#export-info-suite). You can use `kExportInfo_UsePreviewFiles` to check if the user has checked "Use Previews" in the Export Settings dialog. If so, if possible, reuse any preview files already rendered. You can use `kExportInfo_NumAudioChannels` to get the number of audio channels in a given source. 10 | 11 | This can be used to automatically initialize the audio channel parameter in the Audio tab of the Export Settings to match the source. 12 | 13 | In the [Export Param Suite](suites.md#export-param-suite), a new function, `MoveParam()`, can be used to move an existing parameter to a new location. 14 | 15 | --- 16 | 17 | ## What's New in CS6 18 | 19 | Exporters can now use the [Exporter Utility Suite](suites.md#exporter-utility-suite) for "push" model compression. The exporter host can simply push frames to a thread-safe exporter-specified callback. This will cut down on the code previously required for render loop management. It should also yield substantial performance increases for exporters that haven't finely tuned their multithreaded rendering. The "pull" model is still supported, and required for Encore and legacy versions of Premiere Pro and Media Encoder. 20 | 21 | The new [Export Standard Param Suite](suites.md#export-standard-param-suite) provides the standard parameters used in many built-in exporters. This can greatly reduce the amount of code needed to manage standard parameters for a typical exporter, and guarantee consistency with built-in exporters. 22 | 23 | Stereoscopic video is now supported when exporting directly from Premiere Pro. In other words, when exports are queued to run in Adobe Media Encoder, they can not get stereoscopic video. 24 | 25 | !!! note 26 | Currently, stereoscopic exporters must use the "pull" model and the new `MakeVideoRendererForTimelineWithStreamLabel()` to get rendered frames from multiple video streams. 27 | 28 | [Export Param Suite](suites.md#export-param-suite) now adds SetParamDescription(), to set tooltip strings for parameters. For the three line Export Summary description in the Export Settings dialog, we've swapped the 2nd and 3rd lines so that the bitrate summary comes after the audio summary. We've renamed the structure to make developers aware of this during a recompile. 29 | 30 | Adobe Media Encoder now includes a Preset Browser that provides more organization for presets. Make sure your presets take advantage of this organization, and are shown in your desired proper location in the Preset Browser. 31 | 32 | Exporters can now set events (error, warning, or info) for a specific encode in progress in the Adobe Media Encoder render queue. The existing call in the [Error Suite](../universals/sweetpea-suites.md#error-suite) is not sufficient for AME to relate the event to a specific encode. So the new [Exporter Utility Suite](suites.md#exporter-utility-suite) provides a way for exporters running either in Premiere Pro or Adobe Media Encoder to log events. These events are displayed in the application UI, and are also added to the AME encoding log. 33 | 34 | Multiple exporters are now supported in a single plugin. To support this, `exExporterInfoRec` is now set to exporters on *exShutdown*. 35 | 36 | `exQueryOutputSettingsRec` has a new member, `outUseMaximumRenderPrecision`, moving knowledge of this render parameter to the exporter. 37 | 38 | --- 39 | 40 | ## What's New in CS5.5 41 | 42 | A new call, `RenderVideoFrameAndConformToPixelFormat`, has been added to the [Sequence Render Suite](suites.md#sequence-render-suite). This allows an exporter to request a rendered frame and then conform it to a specific pixel format. 43 | 44 | A new return value, `exportReturn_ParamButtonCancel`, has been added to signify that an exporter is returning from `exSelParamButton` without modifying anything. 45 | 46 | ### Export Controller API 47 | 48 | We have opened up a new export controller API that can drive any exporter to generate a file in any format and perform custom post-processing operations. Developers wanting to integrate Premiere Pro with an asset management system will want to use this API instead. 49 | 50 | --- 51 | 52 | ## What's New in CS5 53 | 54 | `exQueryOutputFileListAfterExportRec` is now `exQueryOutputFileListRec`, with a slight change to the structure order. 55 | 56 | We've also fixed a few bugs, such as bug 1925419, where all sliders would be given a checkbox to disable the control, as if exParamFlag_optional had been set. 57 | 58 | We've made a couple new attributes available to exporters via the `GetExportSourceInfo()` call - the video poster frame time, and the source timecode. 59 | 60 | 3rd-party exporters can now be used to transcode assets to MPEG-2 or Blu-ray compliant files. 61 | 62 | --- 63 | 64 | ## Porting From the Compiler API 65 | 66 | The export API replaces the old compiler API from CS3 and earlier versions. The export API combines the processing speed and quality of the old compiler API, with the UI flexibility of Media Encoder. Although the selectors and structures have been renamed and reorganized, much of the code that deals with rendering and writing frames is mostly the same. 67 | 68 | The parameter UI is what has changed the most. Rather than having a standard set of parameters as standard compilers had, or having a completely custom UI as custom compilers had, in 69 | 70 | the new exporter API, all parameters must be explicitly added using the [Export Param Suite](suites.md#export-param-suite). First register the parameters during `exSelGenerateDefaultParams`, and then provide the localized strings and constrained parameter values during `exSelPostProcessParams`. When the exporter is sent `exSelExport` to export, get the parameter values, again using the [Export Param Suite](suites.md#export-param-suite). 71 | -------------------------------------------------------------------------------- /docs/universals/audio.md: -------------------------------------------------------------------------------- 1 | # Audio 2 | 3 | ## 32-bit Float, Uninterleaved Format 4 | 5 | All audio calls to and from Premiere use arrays of buffers of 32-bit floats to pass audio. Audio is not interleaved, rather separate channels are stored in separate buffers. So the structure for stereo audio looks like this: 6 | 7 | ```cpp 8 | float* audio[2]; 9 | ``` 10 | 11 | where `audio[0]` is the address of a buffer N samples long, and `audio[1]` is the address of a second buffer N samples long. `audio[0]` contains the left channel, and `audio[1]` contains the right channel. N is the number of sample frames in the buffer. 12 | 13 | Since Premiere uses 32-bit floats for each audio sample, it can represent values above 0 dB. 0 dB corresponds to +/- 1.0 in floating point. A floating point sample can be converted to a 16-bit short integer by multiplying by 32767.0 and casting the result to a short. 14 | 15 | E.g.: 16 | 17 | ```cpp 18 | sample16bit[n] = (short int) (sample32bit[n] * 32767.0) 19 | ``` 20 | 21 | The plugin is responsible for converting to and from the 32-bit uninterleaved format when reading a file that uses a different format. There are calls to convert between formats in the [Audio Suite](sweetpea-suites.md#audio-suite). For symmetry in the int <-> float conversions, we recommend you use the utility functions provided. 22 | 23 | --- 24 | 25 | ## Audio Sample Types 26 | 27 | Since 32-bit floats are the only audio format ever passed, there is no option of sample type or bit depth. However, file formats do use a variety of sample types and bit depths, so `AudioSampleTypes` define a variety of possible formats. 28 | 29 | These formats are used to set members in structures passed to Premiere to define the user interface, and do not affect the format of the audio passed to and from Premiere. 30 | 31 | | PrAudioSampleType | Description | 32 | | ---------------------------------------- | --------------------------------------------- | 33 | | `kPrAudioSampleType_8BitInt` | 8-bit integer | 34 | | `kPrAudioSampleType_8BitTwosInt` | 8-bit integer, two's complement | 35 | | `kPrAudioSampleType_16BitInt` | 16-bit integer | 36 | | `kPrAudioSampleType_24BitInt` | 24-bit integer | 37 | | `kPrAudioSampleType_32BitInt` | 32-bit integer | 38 | | `kPrAudioSampleType_32BitFloat` | 32-bit floating point | 39 | | `kPrAudioSampleType_64BitFloat` | 64-bit floating point | 40 | | `kPrAudioSampleType_16BitIntBigEndian` | 16-bit integer, big endian | 41 | | `kPrAudioSampleType_24BitIntBigEndian` | 24-bit integer, big endian | 42 | | `kPrAudioSampleType_32BitIntBigEndian` | 32-bit integer, big endian | 43 | | `kPrAudioSampleType_32BitFloatBigEndian` | 32-bit floating point, big endian | 44 | | `kPrAudioSampleType_Compressed` | Any non-PCM format | 45 | | `kPrAudioSampleType_Packed` | Any PCM format with mixed sample types | 46 | | `kPrAudioSampleType_Other` | A sample type not in this list | 47 | | `kPrAudioSampleType_Any` | Any available sample type (used by exporters) | 48 | 49 | --- 50 | 51 | ## Audio Sample Frames 52 | 53 | A sample frame is a unit of measurement for audio. One audio sample frame describes all channels of one sample of audio. Each sample is a 32-bit float. Thus, the storage requirement of an audio sample frame in bytes is equal to `4 * number of channels`. 54 | 55 | --- 56 | 57 | ## Audio Sample Rate 58 | 59 | `PrAudioSample` is a `prInt64` 60 | 61 | --- 62 | 63 | ## Audio Channel Types 64 | 65 | Premiere currently supports four different audio channel types: mono, stereo, 5.1, and max channel. 66 | 67 | Greater than 5.1 channel support was originally added in Premiere Pro 4.0.1, with partial support for a 16 channel master audio track, only for importing OMFs and playing out to hardware. 68 | 69 | In CS6, 16-channel audio export was added. 70 | 71 | Starting in CC, the audio channel support is increased to 32 channels. 72 | 73 | | PrAudioChannelType | Description | 74 | |----------------------------------|-----------------------------------------------------------| 75 | | `kPrAudioChannelType_Mono` | Mono | 76 | | `kPrAudioChannelType_Stereo` | Stereo. The order of the stereo channels is: | 77 | | | | 78 | | | `kPrAudioChannelLabel_FrontLeft` | 79 | | | `kPrAudioChannelLabel_FrontRight` | 80 | | `kPrAudioChannelType_51` | 5.1 audio. | 81 | | | The order of the 5.1 channels is: | 82 | | | `kPrAudioChannelLabel_FrontLeft` | 83 | | | `kPrAudioChannelLabel_FrontRight` | 84 | | | `kPrAudioChannelLabel_BackLeft` | 85 | | | `kPrAudioChannelLabel_BackRight` | 86 | | | `kPrAudioChannelLabel_FrontCenter` | 87 | | | `kPrAudioChannelLabel_LowFrequency` | 88 | | | `kPrAudioChannelLabel_BackLeft` | 89 | | | `kPrAudioChannelLabel_BackRight` | 90 | | `kPrAudioChannelType_MaxChannel` | New in CC. | 91 | | | `kMaxAudioChannelCount`, defined as 32 channels as of CC. | 92 | | | All channels use `kPrAudioChannelLabel_Discrete`. | 93 | -------------------------------------------------------------------------------- /docs/transmitters/transmitter-basics.md: -------------------------------------------------------------------------------- 1 | # Transmitter Basics 2 | 3 | ## Basic Organization 4 | 5 | A transmitter module can define multiple plugins. Each plugin can appear in the Playback Preferences as an option for video playback and/or audio playback. Only one transmitter can be used for audio, since the transmitter used for audio drives the clock. Multiple transmitters may be selected for video simultaneously. 6 | 7 | When active, multiple instances of a single plugin can be created. An instance is created to display a clip or sequence. Hardware access is regulated through ActivateDeactivate. Only an active instance should access the hardware. 8 | 9 | --- 10 | 11 | ## Video Formats 12 | 13 | Specify which video format(s) you wish to receive during QueryVideoMode. To simplify your plugin, be as specific as possible, and allow the host to perform the conversion asynchronously ahead of time. Packed and compressed formats are also supported. If multiple formats are specified, the closest will be selected at render time. If your transmitter would benefit from on-GPU frames, please let us know. 14 | 15 | When sent QueryVideoMode, the transmitter is informed about the clip/sequence video attributes by being passed a tmInstance pointer. So, for example, if the transmitter instance is constructed to support a 1920x1080 timeline, it can report that same size back to the host application, so that it will not have to handle any scaling. If, for example, it does handle scaling, and it is constructed to handle a 1440x1080 timeline, it can report 1440x1080 and handle the scaling itself. In this way you can choose a single fixed size depending on the timeline. 16 | 17 | When video frames are pushed to the transmitter, properties like pixel format may change on a segment-by-segment basis depending on the source footage. Other properties like size may change based on the current fractional resolution, which may differ between scrubbing and stopped. 18 | 19 | --- 20 | 21 | ## Fractional Resolution 22 | 23 | In the Premiere Pro Source and Program Monitors, the user can choose independent resolutions for rendering during playback and paused modes. For example, it is common to have the playback resolution set to half, and paused resolution set to full. 24 | 25 | If an output card has a hardware scaler, the transmit plugin can declare support for fractional resolutions. For example, for a 1920x1080 instance, it could declare support for not only 26 | 27 | 1920x1080, but also 960x540, 480x270, etc. This will allow the renderer to skip the step of rescaling back up to full resolution after rendering at a fractional resolution. If however, the plugin only declares support for full resolution, the renderer will scale the video back up before pushing it to the transmitter. 28 | 29 | --- 30 | 31 | ## Audio Format 32 | 33 | During QueryAudioMode, a transmitter will be told how many channels the instance has. The transmitter should change that value based on what it can support and then make sure the buffers it provides match that. Although Premiere Pro can support 32 channels of audio, transmitters can only support up to 16 channels of audio. 34 | 35 | As of CS6, sequences will currently always report audio available in CreateInstance, even if empty. An example of somewhere that a transmitter will be called with no audio is for video output from the RED settings dialog, which is video only. 36 | 37 | A transmitter should call GetNextAudioBuffer only when inAudioActive is passed as true to ActivateDeactivate. 38 | 39 | --- 40 | 41 | ## Frame Rate 42 | 43 | For framerate, video will be pushed to you at the rate of the timeline. This was chosen because of the wide variety in conversion policies, including pulldown, frame duplication, etc. 44 | 45 | --- 46 | 47 | ## Dropped Frames 48 | 49 | If the host cannot keep up rendering, it will send duplicate frames with PushVideo. If you receive a frame that cannot be sent out to hardware on time, notify the host using inDroppedFrame Callback in tmPlaybackClock. In Premiere Pro, the user can turn on the Dropped Frame Indicator to see the total number of frames that were dropped either because the host couldn't keep up, or the hardware couldn't keep up. 50 | 51 | --- 52 | 53 | ## Sync Between Application UI and Hardware Output 54 | 55 | Naturally there is some latency between the time the host sends frames to be displayed on the output, and the time it can actually be displayed. Use tmVideoMode.outLatency to specify the latency. For example, if a transmitter specifies 5 frames of latency, when the user starts playback, the host will send 5 frames of video to the transmitter before sending StartPlaybackClock. This allows time for the transmitter to send frames to the hardware output in advance, so that the hardware output will be in sync with the monitor in the host application UI. 56 | 57 | When the user is scrubbing in the timeline, send the video frames as fast as possible to the output. The host application UI will not wait for the hardware output to catch up, and there may be noticable latency. To reduce the scrubbing latency as much as possible, cancel any pending frames to immediately display the new one. 58 | 59 | --- 60 | 61 | ## Closed Captioning 62 | 63 | This captioning data is attached to a sequence by the user via menu items in the Sequence menu. In the Program Monitor, the Closed Captioning Display options in the fly-out menu give the user control over the display. The hardware should always transmit any Closed Captioning data, and the user can go through the hardware monitor's on-screen display menu to choose which caption track to view. The closed captioning data is accessible using the new [Captioning Suite](../universals/sweetpea-suites.md#captioning-suite). Use this data for the hardware output. 64 | 65 | --- 66 | 67 | ## Driving Transmitters from Other Plugins 68 | 69 | Transmitters can be driven by many areas of the Premiere Pro interface. Currently, they are called to show frames from the Program Monitor and Source Monitor. But other types of plugins can use the [Transmit Invocation Suite](suites.md#transmit-invocation-suite) to push frames to transmitters. For example, an effect or titler with a modal setup dialog could push frames to the output. 70 | 71 | --- 72 | 73 | ## Entry Point 74 | 75 | This entry point function will be called once on load, and once on unload. 76 | 77 | ```cpp 78 | tmResult (*tmEntryFunc)( 79 | csSDK_int32 inInterfaceVersion, 80 | prBool inLoadModule, 81 | piSuitesPtr piSuites, 82 | tmModule* outModule) 83 | ``` 84 | 85 | A tmModule is a structure of function pointers, which the transmitter implements. 86 | -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | # Do not modify below line! Inherits common components. 2 | INHERIT: ./docs/_global/mkdocs.yml 3 | 4 | #### Site metadata & nav - update these! 5 | 6 | site_name: Premiere Pro C++ SDK Guide 7 | site_url: https://ppro-plugins.docsforadobe.dev/ 8 | repo_url: https://github.com/docsforadobe/premiere-plugin-guide/ 9 | repo_name: "premiere-plugin-guide" 10 | 11 | nav: 12 | - Home: index.md 13 | - History: 14 | - Version History: history.md 15 | - Introduction: 16 | - What Premiere Plug-Ins Do: intro/what-premiere-plugins-do.md 17 | - SDK Audience: intro/sdk-audience.md 18 | - Whats New: intro/whats-new.md 19 | - Where Do I Start: intro/where-do-i-start.md 20 | - Document Overview: intro/document-overview.md 21 | - Getting Support and Providing Feedback: intro/getting-support.md 22 | - Premiere Pro Plug-In Types: intro/premiere-pro-plugin-types.md 23 | - Sample Projects: intro/sample-projects.md 24 | - Debugging Plug-Ins: intro/debugging-plugins.md 25 | - Load Em Up: intro/load-em-up.md 26 | - Plug In Installation: intro/plugin-installation.md 27 | - Localization: intro/localization.md 28 | - Best Practices: intro/best-practices.md 29 | - Resources: 30 | - Resources: resources/resources.md 31 | - Plug-In Property Lists (PiPL) Resource: resources/pipl-resource.md 32 | - IMPT Resource: resources/impt-resource.md 33 | - Universals: 34 | - Universals: universals/universals.md 35 | - Time: universals/time.md 36 | - Video Frames: universals/video-frames.md 37 | - Pixel Formats And Color Spaces: universals/pixel-formats-and-color-spaces.md 38 | - Pixel Aspect Ratio: universals/pixel-aspect-ratio.md 39 | - Fields: universals/fields.md 40 | - Audio: universals/audio.md 41 | - Memory Management: universals/memory-management.md 42 | - Basic Types Structures: universals/basic-types-structures.md 43 | - Suites: universals/suites.md 44 | - SweetPea Suites: universals/sweetpea-suites.md 45 | - Legacy Callback Suites: universals/legacy-callback-suites.md 46 | - Hardware Integration: 47 | - Hardware: hardware/hardware.md 48 | - Hardware Integration Components: hardware/hardware-integration-components.md 49 | - ClassID, Filetype and Subtype: hardware/classid-filetype-subtype.md 50 | - ClassData Functions: hardware/classdata-functions.md 51 | - Importers: 52 | - Importers: importers/importers.md 53 | - What's New: importers/whats-new.md 54 | - Getting Started: importers/getting-started.md 55 | - Selector Table: importers/selector-table.md 56 | - Selector Descriptions: importers/selector-descriptions.md 57 | - Return Codes: importers/return-codes.md 58 | - Structures: importers/structures.md 59 | - Structure Descriptions: importers/structure-descriptions.md 60 | - Suites: importers/suites.md 61 | - Export Controllers: 62 | - Export Controllers: export-controllers/export-controllers.md 63 | - Exporters: 64 | - Exporters: exporters/exporters.md 65 | - Whats New: exporters/whats-new.md 66 | - Getting Started: exporters/getting-started.md 67 | - Selector Table: exporters/selector-table.md 68 | - Selector Descriptions: exporters/selector-descriptions.md 69 | - Return Codes: exporters/return-codes.md 70 | - Structures: exporters/structures.md 71 | - Structure Descriptions: exporters/structure-descriptions.md 72 | - Suites: exporters/suites.md 73 | - Additional Details: exporters/additional-details.md 74 | - Transmitters: 75 | - Transmitters: transmitters/transmitters.md 76 | - Transmitter Basics: transmitters/transmitter-basics.md 77 | - tmModule Functions: transmitters/tmModule-functions.md 78 | - tmModule Structures: transmitters/tmModule-structures.md 79 | - Suites: transmitters/suites.md 80 | - Video Filters: 81 | - Video Filters: video-filters/video-filters.md 82 | - Whats New: video-filters/whats-new.md 83 | - Getting Started: video-filters/getting-started.md 84 | - Selector Table: video-filters/selector-table.md 85 | - Selector Descriptions: video-filters/selector-descriptions.md 86 | - Return Codes: video-filters/return-codes.md 87 | - VideoRecord: video-filters/VideoRecord.md 88 | - Additional Details: video-filters/additional-details.md 89 | - GPU Effects & Transitions: 90 | - GPU Effects & Transitions: gpu-effects-transitions/gpu-effects-transitions.md 91 | - Getting Started: gpu-effects-transitions/getting-started.md 92 | - CUDA, OpenCL, Metal, or OpenGL?: gpu-effects-transitions/cuda-opencl-metal-opengl.md 93 | - What's New in Premiere Pro 12.0?: gpu-effects-transitions/whats-new-in-ppro-12.md 94 | - What's New in Premiere Pro CC 2015.4?: gpu-effects-transitions/whats-new-in-ppro-cc2015.md 95 | - What's New in Premiere Pro CC 2014?: gpu-effects-transitions/whats-new-in-ppro-cc2014.md 96 | - PrGPUFilter Function Table: gpu-effects-transitions/PrGPUFilter-function-table.md 97 | - Function Descriptions: gpu-effects-transitions/function-descriptions.md 98 | - Return Codes: gpu-effects-transitions/return-codes.md 99 | - Structure Descriptions: gpu-effects-transitions/structure-descriptions.md 100 | - PrGPU SDK Macros: gpu-effects-transitions/PrGPU-SDK-macros.md 101 | - Suites: gpu-effects-transitions/suites.md 102 | - AE Transition Extensions: 103 | - Getting Started: ae-transition-extensions/getting-started.md 104 | - AE Transition Extensions: ae-transition-extensions/ae-transition-extensions.md 105 | - PF_TransitionSuite: ae-transition-extensions/PF_TransitionSuite.md 106 | - Control Surfaces: 107 | - Control Surfaces: control-surfaces/control-surfaces.md 108 | 109 | #### Additional config below - modify sparingly! 110 | 111 | extra: 112 | # Custom guide-specific overrides 113 | # 114 | # Valid keys are: 115 | # custom_dir: str 116 | # hooks: 117 | # - path/to/hook.py 118 | # not_in_nav: 119 | # - gitignore_style/path/to/exclude 120 | # theme_features: 121 | # - theme.feature 122 | overrides: {} 123 | 124 | # CSS for this guide 125 | extra_css: 126 | - _static/extra.css 127 | 128 | # JS for this guide 129 | extra_javascript: 130 | - _static/extra.js 131 | 132 | markdown_extensions: {} 133 | 134 | plugins: {} 135 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/PrGPU-SDK-macros.md: -------------------------------------------------------------------------------- 1 | # PrGPU SDK Macros 2 | 3 | The PrGPU SDK macros and device functions allow you to write kernels that will compile on multiple GPU compute languages - CUDA, OpenCL, and Metal. These languages have an enormous overlap - a C98 language subset, and by using the porting macros and functions to abstract out the differences, you can write portable code. You can still access API specific features not covered by the porting set but you'll need to include an alternate code path for the other APIs. 4 | 5 | Currently the SDK does not provide host side code to compile or launch arbitrary kernels, but there are SDK examples that show how to do this for the different APIs. 6 | 7 | The macros are not part of the plugin API - they are provided as a utility if you would like to used them. This gives you broad latitude to fork them and make any changes you see fit without breaking plugin compatibility. On the Adobe end, we may expand and modify the SDK kernel porting set in future releases to cover other compute APIs or other enhancements. 8 | 9 | --- 10 | 11 | ## External Dependencies 12 | 13 | The macros do add one external source dependency - Boost (boost.org). We use the Boost preprocessor package to manipulate kernel definitions. 14 | 15 | Depending on how you choose to compile and deploy your kernels, we also provide a small python script that may be useful (See "Preprocessing as a Separate Step") 16 | 17 | --- 18 | 19 | ## Include Paths 20 | 21 | You need to add some include paths to your kernel compilation environment: 22 | 23 | - the path to PrGPU/KernelSupport/ (found in the SDK at Examples/Projects/GPUVideoFilter/ Utils/) 24 | - the path to the Boost library 25 | 26 | --- 27 | 28 | ## Defines 29 | 30 | You will also need to define a symbol to tell the header file what API to process when compiling the kernel: 31 | 32 | - Metal: 33 | `DGF_DEVICE_TARGET_METAL=1` 34 | - OpenCL: 35 | `DGF_DEVICE_TARGET_OPENCL=1` 36 | `DGF_OPENCL_SUPPORTS_16F=1` or `0`, depending on whether you will support half (16-bit float) access for this device. Some older cards are quite slow at half support, or just don't support it. 37 | - CUDA: 38 | the KernelCore.h header will automatically sense the cuda compiler and will `#define GF_DEVICE_TARGET_CUDA 1` for you. 39 | 40 | Only one device target flag will be active in any given compilation. The header the define the device target macros to 0 for the inactive APIs. Feel free to use these macros in your code for any API specializations. Outside of the header, we don't need to do this much. 41 | 42 | --- 43 | 44 | ## Header Files 45 | 46 | - KernelCore.h - basic header macros. You'll certainly want these 47 | - KernelMemory.h - global device memory access abstractions for float and half 48 | - FloatingPoint.h - common floating point routines. These mostly hide naming differences across APIs. 49 | 50 | You'll want to include them like this in your kernel: 51 | 52 | ```cpp 53 | #include "PrGPU/KernelSupport/KernelCore.h" 54 | ``` 55 | 56 | The folder contains additional files used by the above files. 57 | 58 | One thing to watch out for is whether your projects are tracking header dependencies properly. If not, you'll need to manually recompile kernels when include files change. This is true whether or not you use the SDK porting set, so you've likely already sorted this out. 59 | 60 | --- 61 | 62 | ## Top Level Kernel Files 63 | 64 | You can organize your code and projects as you like, but we find it convenient to have separate top level kernel files for each API (.cl, .cu, and .metal) that just include shared code and are otherwise nearly empty. This makes build rules much easier. 65 | 66 | --- 67 | 68 | ## Preprocessing as a Separate Step 69 | 70 | If you compile the kernel source on the customer machine, you may wish to preprocess the kernel at plugin compile time, and store the kernel source in your plugin. A python script (Python version 3 or greater required) is provided that will convert preprocessed source to a character array. The script is in Examples/Projects/GPUVideoFilter/Utils/CreateCString.py. See the ProcAmp example for usage. 71 | 72 | You can also compile kernels (which is always the case for CUDA) at plugin compile time, in which case you don't need the python script, or a separate preprocessing run. You will need to package the compiled kernel in your plugin if you go this route. 73 | 74 | The ProcAmp example uses a preprocessing step for OpenCL. 75 | 76 | --- 77 | 78 | ## Declaring Kernels 79 | 80 | Metal kernels require syntax that is quite different than CUDA, and the PrGPU macros use the Boost preprocessing package to express parameters. This is by far the most complicated part of the package, so grab a fresh cup of coffee and sit back for a read. 81 | 82 | The GF_KERNEL_FUNCTION macro is used to pass values as parameters (CUDA) or in a struct (metal). The macro will create an API-specific kernel entry point which will call a 83 | 84 | function that it defines, leaving you to fill in the body. The macro uses Boost preprocessor sequences to express a type/name pair: 85 | 86 | ```cpp 87 | (float)(inValue) 88 | ``` 89 | 90 | These pairs are then nested into a sequence of parameters: 91 | 92 | ```cpp 93 | ((float)(inAge))((int)(inMarbles)) 94 | ``` 95 | 96 | There are different categories of parameters, such as buffers, values, and kernel position. Each category sequence is a separate macro parameter. Example usage: 97 | 98 | ```cpp 99 | GF_KERNEL_FUNCTION(RemoveFlicker, 100 | 101 | //kernel name, then comma, ((GF_PTR(float4))(inSrc)) 102 | 103 | //all buffers and textures go after the first comma 104 | ((GF_PTR(float4))(outDest)), 105 | ((int)(inDestPitch)) 106 | 107 | //After the second comma, all values to be passed ((DevicePixelFormat)(inDeviceFormat)) 108 | ((int)(inWidth)) 109 | ((int)(inHeight)), 110 | ((uint2)(inXY)(KERNEL_XY)) 111 | 112 | //After the third comma, the position arguments. 113 | ((uint2)(inBlockID)(BLOCK_ID))) 114 | { 115 | // 116 | } 117 | ``` 118 | 119 | In the example above, the host does not pass the position values when invoking the kernel. 120 | 121 | Position values are filled in automatically by the unmarshalling code generated by the GF_KERNEL_FUNCTION macro. The code you write will actually end up in a device function that the unmarshalling code will call. See the ProcAmp example plugin for usage. 122 | 123 | Kernels that use statically sized shared memory use a different macro, `GF_KERNEL_FUNCTION_SHARED`. Please see the header for details. 124 | 125 | --- 126 | 127 | ## Declaring Device Functions 128 | 129 | By comparison, device functions are a snap to write: 130 | 131 | ```cpp 132 | GF_DEVICE_FUNCTION float Average(float a, float b) {... 133 | ``` 134 | 135 | --- 136 | 137 | ## Other Macros and Functions 138 | 139 | There's a variety of other macros and functions in the KernelSupport headers. Please see the Headers and examples for details. 140 | -------------------------------------------------------------------------------- /docs/intro/sample-projects.md: -------------------------------------------------------------------------------- 1 | # Sample Projects 2 | 3 | ## SDK File Importer 4 | 5 | This importer supports .sdk media files. To use the importer, choose File > Import, and select an .sdk file. Such files may be created using the SDK Exporter. It supports uncompressed 8-bit RGB with or without alpha, and packed 10-bit YUV (v410), and supports mono, stereo, and 5.1 audio at arbitrary sample rates and 32-bit float. It supports trimming using the Project Manager, Properties and Data Rate Analysis, Unicode filenames, the avoidAudioConform flag, and can read video frames asynchronously. It also features a test harness for multistream audio, which can be turned on by uncommenting the `MULTISTREAM_AUDIO_TESTING` define in the header. 6 | 7 | ## Synth Import 8 | 9 | This synthetic importer generates 8-bit YUV and RGB, video only. To use it, choose File > New > SDK Synthetic Importer. When the clip is created, it demonstrates a sample settings dialog, which can be displayed again by double-clicking the clip in the Project Panel or Timeline Panel. Every time the settings dialog is displayed, it creates new footage in memory. It creates ten seconds of footage at 24 fps. The video consists of horizontal lines of random colors. 10 | 11 | ## SDK Custom Import 12 | 13 | This custom importer creates a clip similar to the Synth Import sample, but generates it to disk, rather than memory. To use it, choose File > New > SDK Custom Importer. You could also import an existing .sdkc media file from the File > Import dialog. After the sample settings dialog, it optionally displays a background frame from the timeline (useful for titlers). 14 | 15 | ## Export Controller 16 | 17 | Adds a new menu item to File > Export > SDK Export Controller. When selected, it displays a simple message box on Windows, takes the DV NTSC widescreen preset, and exports a file to `C:\Windows\Temp` on Windows, or to the Desktop on macOS. 18 | 19 | ## SDK Exporter 20 | 21 | This exporter writes .sdk files. To use it, choose File > Export > Media, and in the Export Settings choose File Type: SDK File. It supports uncompressed 8-bit RGB with or without alpha, and packed 10-bit YUV (v410). It supports mono, stereo, and 5.1 audio at arbitrary sample rates and 32-bit float. It demonstrates custom parameters, including a custom settings button. It also writes marker data to an .html file with the same filename. To write files with v410 compression using 8-bit RGB sources, this sample uses routines to convert the 8-bit RGB data to 32-bit RGB, then to 32-bit YUV, and finally to v410. These same routines may be adapted for transitions, filters, and other plugin types. 22 | 23 | ## Transmitter 24 | 25 | The sample transmit plugin does not output to any hardware, but can be used to step through interactions between the host and plugin in the debugger. To use it, go the the Preferences > Playback, and choose the SDK Transmitter as the Audio Device, and as a Video Device. This transmit plugin provides the basic structure, separating concepts of plugin and instance. For video, it declares support for any pixel format and resolution. For audio, it declares support for 2 channels. It also declares a small latency value for demonstrative purposes. On Windows, there is some basic debug logging. It does not actually provide it's own clock at this time, but on playback it simply pretends to step forward a frame with every frame received. This may result in some bug behavior such as playing back at speeds faster or slower than normal, depending on how fast the host can push frames. 26 | 27 | ## SDK_ProcAmp 28 | 29 | This GPU-accelerated effect demonstrates a simple ProcAmp effect using the After Effects API with the Premiere Pro GPU extensions. The effect is found in the SDK folder of the Video Effects in the Effects Control panel. It supports Metal acceleration. 30 | 31 | ## Vignette 32 | 33 | This effect creates a vignette on video using the After Effects API with the Premiere Pro GPU extensions. Has CUDA and software render paths. Software rendering in Premiere Pro includes 8-bit/32-bit RGB/ YUV software render paths. Software rendering in After Effects includes 8-bit and 32-bit smart rendering.Thanks to Bart Walczak for donating this sample. 34 | 35 | ## SDK_CrossDissolve 36 | 37 | This GPU-accelerated transition demonstrates a simple cross dissolve transition using the After Effects API with the transition extensions. The transition is found in the SDK folder of the Video Transitions in the Effects Control panel. It supports CUDA acceleration. 38 | 39 | ## ControlSurface 40 | 41 | You should see the plugin in the PPro UI in Preferences > Control Surface, when you hit the Add button, as one of the options in the Device Class drop-down next to Mackie and EUCON (currently shows as "SDK Control Surface Sample"). Since Adobe doesn't make hardware, consider this sample as a starting point for you to add your own functionality. 42 | 43 | ## How To Build the SDK Sample Projects 44 | 45 | The required development environment is described in [SDK Audience](sdk-audience.md). 46 | 47 | See a [quickstart video](https://assets.adobe.com/public/08c43fb7-4633-4007-5201-b3b77405d770?scid=social_20180227_75678337) on building an effect using a similar SDK (on macOS) . 48 | 49 | We've combined the sample projects into a single master project, stored in the Examples folder of the SDK. 50 | 51 | For macOS it is **BuildAll.xcodeproj**; for Windows, it is **BuildAll.sln**. 52 | 53 | You'll need to specify some settings so that the plugins are built into a folder where they will be loaded by the application you are developing for. 54 | 55 | Build plugins into the following folder for macOS: 56 | 57 | /Library/Application Support/Adobe/Common/Plugins/7.0/MediaCore/ 58 | 59 | ...and the following path for Windows: 60 | 61 | [Program Files]\Adobe\Common\Plugins\7.0\MediaCore\ 62 | 63 | **NOTE**: Version is locked at 7.0 for all CC versions, or CSx for earlier versions. 64 | 65 | In XCode, set the build location for the project in File > Project Settings. Press the Advanced button. Under Build Location choose Custom, select Absolute, and set the Products path. 66 | 67 | In Visual Studio, for convenience, we have set the Output File for all sample projects to use the base path set by the environment variable `PREMSDKBUILDPATH`. You'll need to set this as a user environment variable for your system, and shown in the screenshot below. 68 | 69 | ![Setting Environment Variables](../_static/env-vars.png "Setting Environment Variables") 70 | 71 | ## Setting Environment Variables 72 | 73 | 1. On Windows, right-click *My Computer > Properties*, and in the left sidebar choose *Advanced System Settings*. 74 | 2. In the dialog that appears, hit the *Environment Variables* button. 75 | 3. In the *User variables*, create a new variable named `PREMSDKBUILDPATH`, with the path as described above. 76 | 4. Log out of Windows, and log back in so that the variable will be set. 77 | 78 | When compiling the plugins, if you see a link error like "Cannot open file `/path/to/plugin.prm`", re-launch Visual Studio in Administrator mode. 79 | 80 | It's not recommended to copy plugins into the plugin folder after you've built them, because that won't allow you to debug the plugins while the host application is running. 81 | -------------------------------------------------------------------------------- /docs/exporters/selector-descriptions.md: -------------------------------------------------------------------------------- 1 | # Selector Descriptions 2 | 3 | This section provides a brief overview of each selector and highlights implementation issues. 4 | 5 | Additional implementation details are at the end of the chapter. 6 | 7 | --- 8 | 9 | ## exSelStartup 10 | 11 | - param1 - [exExporterInfoRec*](structure-descriptions.md#exexporterinforec) 12 | - param2 - `unused` 13 | 14 | Sent during application launch, unless the exporter has been cached. 15 | 16 | A single exporter can support multiple codecs and file extensions. 17 | 18 | `exExporterInfoRec` describes the exporter's attributes, such as the format display name. 19 | 20 | --- 21 | 22 | ## exSelBeginInstance 23 | 24 | - param1 - [exExporterInstanceRec*](structure-descriptions.md#exexporterinstancerec) 25 | - param2 - `unused` 26 | 27 | Allocate any private data. 28 | 29 | --- 30 | 31 | ## exSelGenerateDefaultParams 32 | 33 | - param1 - [exGenerateDefaultParamRec*](structure-descriptions.md#exgeneratedefaultparamrec) 34 | - param2 - `unused` 35 | 36 | Set the exporter's default parameters using the [Export Param Suite](suites.md#export-param-suite). 37 | 38 | --- 39 | 40 | ## exSelPostProcessParams 41 | 42 | - param1 - [exPostProcessParamsRec*](structure-descriptions.md#expostprocessparamsrec) 43 | - param2 - `unused` 44 | 45 | Post process parameters. This is where the localized strings for the parameter UI must be provided. 46 | 47 | --- 48 | 49 | ## exSelValidateParamChanged 50 | 51 | - param1 - [exParamChangedRec*](structure-descriptions.md#exparamchangedrec) 52 | - param2 - `unused` 53 | 54 | Validate any parameters that have changed. Based on a change to a parameter value, the exporter may update other parameter values, or show/hide certain parameter controls, using the [Export Param Suite](suites.md#export-param-suite). 55 | 56 | To notify the host that the plugin is changing other parameters, set `exParamChangedRec.rebuildAllParams` to a non-zero value. 57 | 58 | --- 59 | 60 | ## exSelGetParamSummary 61 | 62 | - param1 - [exParamSummaryRec*](structure-descriptions.md#exparamsummaryrec) 63 | - param2 - `unused` 64 | 65 | Provide a text summary of the current parameter settings, which will be displayed in the summary area of the Export Settings dialog. 66 | 67 | --- 68 | 69 | ## exSelParamButton 70 | 71 | - param1 - [exParamButtonRec*](structure-descriptions.md#exparambuttonrec) 72 | - param2 - `unused` 73 | 74 | Sent if exporter has one or more buttons in its parameter UI, and the user clicks one of the buttons in the Export Settings. 75 | 76 | The ID of the button pressed is passed in `exParamButtonRec.buttonParamIdentifier`. 77 | 78 | Display any dialog using platform-specific UI, collect any user input, and save any changes back to `privateData`. 79 | 80 | If the user cancels the dialog, return `exportReturn_ParamButtonCancel` to signify that nothing in the `privateData` has changed. 81 | 82 | --- 83 | 84 | ## exSelExport 85 | 86 | - param1 - [exDoExportRec*](structure-descriptions.md#exdoexportrec) 87 | - param2 - `unused` 88 | 89 | Do the export! Sent when the user starts an export to the format supported by the exporter, or if the exporter is used in an Editing Mode and the user renders the work area. 90 | 91 | Single file exporters are sent this selector only once per export (e.g. AVI, QuickTime). To create a single file, setup a loop where you request each frame in the startTime to endTime range using one of the render calls in the [Sequence Render Suite](suites.md#sequence-render-suite) and GetAudio in the [Sequence Audio Suite](suites.md#sequence-audio-suite). For better performance, you can use the asynchronous calls in the [Sequence Render Suite](suites.md#sequence-render-suite) to have the host render multiple frames on multiple threads. 92 | 93 | Still frame exporters are sent `exSelExport` for each frame in the sequence (e.g. numbered TIFFs). The host will name the files appropriately. 94 | 95 | Save render time by checking to see if frames are repeated. Inspect the SequenceRender_GetFrameReturnRec.repeatCount returned from a render call, which holds a frame repeat count. 96 | 97 | --- 98 | 99 | ## exSelExport2 100 | 101 | - param1 - [exDoExportRec2*](structure-descriptions.md#exdoexportrec2) 102 | - param2 - `unused` 103 | 104 | Do the export! Identical to exSelExport, except that exDoExportRec2 (which contains a LUT description) is passed. 105 | 106 | Exporter can specify the ID of the LUT that needs to be applied as last step in export processing. This is for including LUT for doing color space conversion in export path. 107 | 108 | In case LUT is specified, `ExportColorSpace` signifies the output color space of LUT. 109 | 110 | --- 111 | 112 | ## exSelQueryExportFileExtension 113 | 114 | - param1 - [exQueryExportFileExtensionRec*](structure-descriptions.md#exqueryexportfileextensionrec) 115 | - param2 - `unused` 116 | 117 | For exporters that support more than one file extension, specify an extension given the file type. 118 | 119 | If this selector is not supported by the exporter, the extension is specified by the exporter in `exExporterInfoRec.fileTypeDefaultExtension`. 120 | 121 | --- 122 | 123 | ## exSelQueryOutputFileList 124 | 125 | - param1 - [exQueryOutputFileListRec*](structure-descriptions.md#exqueryoutputfilelistrec) 126 | - param2 - `unused` 127 | 128 | For exporters that export to more than one file. This is called before an export for the host to find out which files would need to be overwritten. 129 | 130 | It is called after an export so the host will know about all the files created, for any post encoding tasks, such as FTP. If this selector is not supported by the exporter, the host application will only know about the original path. 131 | 132 | This selector will be called three times. On the first call, the plugin fills out numOutputFiles. The host will then make numOutputFiles count of outputFileRecs, but empty. 133 | 134 | On the second call, the plugin fills out the path length (incl trailing null) for each exOutputFileRec element in outputFileRecs. The host will then allocate all paths in each outputFileRec. 135 | 136 | On the third call, the plugin fills in the path members of the outputFileRecs. 137 | 138 | --- 139 | 140 | ## exSelQueryStillSequence 141 | 142 | - param1 - [exQueryStillSequenceRec*](structure-descriptions.md#exquerystillsequencerec) 143 | - param2 - `unused` 144 | 145 | The host application asks a still-only exporter if it wants to export as a sequence, and at what frame rate. 146 | 147 | --- 148 | 149 | ## exSelQueryOutputSettings 150 | 151 | - param1 - [exQueryOutputSettingsRec*](structure-descriptions.md#exqueryoutputsettingsrec) 152 | - param2 - `unused` 153 | 154 | The host application asks the exporter for general details about the current settings. This is a required selector. 155 | 156 | --- 157 | 158 | ## exSelValidateOutputSettings 159 | 160 | - param1 - [exValidateOutputSettingsRec*](structure-descriptions.md#exvalidateoutputsettingsrec) 161 | - param2 - `unused` 162 | 163 | The host application asks the exporter if it can export with the current settings. 164 | 165 | The exporter should return `exportReturn_ErrLastErrorSet` if not, and the error string should be set to a description of the failure. 166 | 167 | --- 168 | 169 | ## exSelEndInstance 170 | 171 | - param1 - [exExporterInstanceRec*](structure-descriptions.md#exexporterinstancerec) 172 | - param2 - `unused` 173 | 174 | Deallocate any private data. 175 | 176 | --- 177 | 178 | ## exSelShutdown 179 | 180 | - param1 - `unused` 181 | - param2 - `unused` 182 | 183 | Sent immediately before shutdown. Free all remaining memory and close any open file handles. 184 | 185 | --- 186 | 187 | ## exSelQueryExportColorSpace 188 | 189 | - param1 - [exExporterInstanceRec*](structure-descriptions.md#exqueryexportcolorspacerec) 190 | - param2 - `unused` 191 | 192 | Describe the color space to be used during export. 193 | -------------------------------------------------------------------------------- /docs/gpu-effects-transitions/structure-descriptions.md: -------------------------------------------------------------------------------- 1 | # Structure Descriptions 2 | 3 | ## PrGPUFilterInfo 4 | 5 | This structure contains some basic info about a GPU filter. It provides access to various suites, and access to private data where the instance can allocate memory and store data which will be passed to subsequent functions. 6 | 7 | ```cpp 8 | typedef struct { 9 | csSDK_uint32 outInterfaceVersion; 10 | PrSDKString outMatchName; 11 | } PrGPUFilterInfo; 12 | ``` 13 | 14 | | Member | Description | 15 | | --------------------- | ------------------------------------------------------------------------------------------------------ | 16 | | `outInterfaceVersion` | Set to the GPU API version corresponding to the version defined in the SDK you are using. | 17 | | `outMatchName` | outMatchName must be equal to a registered software filter, if NULL will default to the module's PiPL. | 18 | 19 | --- 20 | 21 | ## PrGPUFilterInstance 22 | 23 | This structure contains some basic info about a GPU filter. It provides access to various suites, and access to private data where the instance can allocate memory and store data which will be passed to subsequent functions. 24 | 25 | ```cpp 26 | typedef struct { 27 | piSuitesPtr piSuites; 28 | csSDK_uint32 inDeviceIndex; 29 | PrTimelineID inTimelineID; 30 | csSDK_int32 inNodeID; 31 | void* ioPrivatePluginData; 32 | prBool outIsRealtime; 33 | } PrGPUFilterInstance; 34 | ``` 35 | 36 | | Member | Description | 37 | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | 38 | | `piSuites` | Standard suites. | 39 | | `inDeviceIndex` | For use with `PrSDKGPUDeviceSuite`. | 40 | | `inTimelineID` | For use with `PrSDKVideoSegmentSuite`. | 41 | | `inNodeID` | For use with `PrSDKVideoSegmentSuite`. | 42 | | `ioPrivatePluginData` | Used by a plugin to store instance data, never touched by the host. | 43 | | `outIsRealtime` | Specify if the plugin is likely to play in real-time, used to determine whether the segment is red, yellow, or unmarked in the timeline. | 44 | 45 | --- 46 | 47 | ## PrGPUFilterRenderParams 48 | 49 | This structure describes the current render request. 50 | 51 | ```cpp 52 | typedef struct { 53 | PrTime inClipTime; 54 | PrTime inSequenceTime; 55 | 56 | // Render properties 57 | PrRenderQuality inQuality; 58 | float inDownsampleFactorX; 59 | float inDownsampleFactorY; 60 | 61 | // Frame properties 62 | csSDK_uint32 inRenderWidth; 63 | csSDK_uint32 inRenderHeight; 64 | csSDK_uint32 inRenderPARNum; 65 | csSDK_uint32 inRenderPARDen; 66 | prFieldType inRenderFieldType; 67 | PrTime inRenderTicksPerFrame; 68 | pmFieldDisplay inRenderField; 69 | } PrGPUFilterRenderParams; 70 | ``` 71 | 72 | | Member | Description | 73 | |-|-| 74 | | `inClipTime` | The time of the current render, relative to clip start | 75 | | `inSequenceTime` | The time of the current render, relative to sequence start | 76 | | `inQuality` | Render quality; one of the `PrRenderQuality` enum values | 77 | | `inDownsampleFactorX` | Horizontal downsample factor | 78 | | `inDownsampleFactorY` | Vertical downsample factor | 79 | | `inRenderWidth` | Video resolution | 80 | | `inRenderHeight` | | 81 | | `inRenderPARNum` | Video pixel aspect ratio, described as a fractional number with separate values for numerator and denominator. | 82 | | `inRenderPARDen` | | 83 | | `inRenderFieldType` | Render field type | 84 | | `inRenderTicksPerFrame` | Video frame rate | 85 | | `inRenderField` | GPU rendering is always done on full-height progressive frames unless `PrGPUFilterFrameDependency.outNeedsFieldSeparation` is `false`. `inRenderField` indicates which field is being rendered. | 86 | 87 | --- 88 | 89 | ## PrGPUFilterFrameDependency 90 | 91 | This structure describes any dependencies for a rendered frame. 92 | 93 | ```cpp 94 | typedef struct { 95 | PrGPUFilterFrameDependencyType outDependencyType; 96 | 97 | // Dependence on other frame times 98 | csSDK_int32 outTrackID; 99 | PrTime outSequenceTime; 100 | 101 | // Dependence on precomputation phase 102 | PrPixelFormat outPrecomputePixelFormat; 103 | csSDK_uint32 outPrecomputeFrameWidth; 104 | csSDK_uint32 outPrecomputeFrameHeight; 105 | csSDK_uint32 outPrecomputeFramePARNumerator; 106 | csSDK_uint32 outPrecomputeFramePARDenominator; 107 | prFieldType outPrecomputeFrameFieldType; 108 | csSDK_size_t outPrecomputeCustomDataSize; 109 | prBool outNeedsFieldSeparation; 110 | } PrGPUFilterFrameDependency; 111 | ``` 112 | 113 | | Member | Description | 114 | |-|-| 115 | | `outDependencyType` | The dependency type. One of: | 116 | | | `PrGPUDependency_InputFrame` | 117 | | | `PrGPUDependency_Precompute` | 118 | | | `PrGPUDependency_FieldSeparation` | 119 | | `outTrackID` | Specify which track is a dependency. Set to 0 for the current track | 120 | | `outSequenceTime` | Set the sequence time which is a dependency. | 121 | | `outPrecomputePixelFormat` | Dependence on precomputation phase | 122 | | `outPrecomputeFrameWidth` | | 123 | | `outPrecomputeFrameHeight` | | 124 | | `outPrecomputeFramePARNumerator` | | 125 | | `outPrecomputeFramePARDenominator` | | 126 | | `outPrecomputeFrameFieldType` | | 127 | | `outPrecomputeCustomDataSize` | Only needed if `outPrecomputePixelFormat` is custom | 128 | | `outNeedsFieldSeparation` | Indicates the plugin may operate on both fields simultaneously (eg non-spatial and non-time varying) | 129 | -------------------------------------------------------------------------------- /docs/exporters/return-codes.md: -------------------------------------------------------------------------------- 1 | # Return Codes 2 | 3 | | Return Code | Reason | 4 | | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | 5 | | `exportReturn_ErrNone` | Operation has completed without error. | 6 | | `exportReturn_Abort` | User aborted the export. | 7 | | `exportReturn_Done` | Export finished normally. | 8 | | `exportReturn_InternalError` | Return this if none of the other errors apply. | 9 | | `exportReturn_OutOfDiskSpace` | Out of disk space error. | 10 | | `exportReturn_BufferFull` | The offset into the buffer would overflow it. | 11 | | `exportReturn_ErrOther` | The vaguer the better, right? | 12 | | `exportReturn_ErrMemory` | Out of memory. | 13 | | `exportReturn_ErrFileNotFound` | File not found. | 14 | | `exportReturn_ErrTooManyOpenFiles` | Too many open files. | 15 | | `exportReturn_ErrPermErr` | Permission violation. | 16 | | `exportReturn_ErrOpenErr` | Unable to open the file. | 17 | | `exportReturn_ErrInvalidDrive` | Invalid drive. | 18 | | `exportReturn_ErrDupFile` | Duplicate filename. | 19 | | `exportReturn_ErrIo` | File I/O error. | 20 | | `exportReturn_ErrInUse` | File is in use. | 21 | | `exportReturn_IterateExporter` | Return value from `exSelStartup` to request exporter iteration. | 22 | | `exportReturn_IterateExporterDone` | Return value from `exSelStartup` to indicate there are no more exporters. | 23 | | `exportReturn_InternalErrorSilent` | Return error code from `exSelExport` to put a custom error message on screen just before returning control to the host. | 24 | | `exportReturn_ErrCodecBadInput` | A video codec refused the input format. | 25 | | `exportReturn_ErrLastErrorSet` | The exporter is returning an error using the [Error Suite](../universals/sweetpea-suites.md#error-suite). | 26 | | `exportReturn_ErrLastWarningSet` | The exporter is returning a warning using the [Error Suite](../universals/sweetpea-suites.md#error-suite). | 27 | | `exportReturn_ErrLastInfoSet` | The exporter is returning information using the [Error Suite](../universals/sweetpea-suites.md#error-suite). | 28 | | `exportReturn_ErrExceedsMaxFormatDuration` | The exporter (or the host) has deemed the duration of the export to be too large. | 29 | | `exportReturn_VideoCodecNeedsActivation` | The current video codec is not activated and cannot be used. | 30 | | `exportReturn_AudioCodecNeedsActivation` | The current audio codec is not activated and cannot be used. | 31 | | `exportReturn_IncompatibleAudioChannelType` | The requested audio channels are not compatible with the source audio. | 32 | | `exportReturn_IncompatibleVideoCodec` | New in CS5. User tried to load a preset with an invalid video codec | 33 | | `exportReturn_IncompatibleAudioCodec` | New in CS5. User tried to load a preset with an invalid audio codec | 34 | | `exportReturn_ParamButtonCancel` | New in CS5.5. Return this from `exSelParamButton` if the user cancelled settings dialog by pressing cancel button. | 35 | | `exportReturn_ErrMediaFormat` | Error encountered writing to media format. | 36 | | `exportReturn_ErrVideoEncoderCreation` | Error encountered while creating video encoder. | 37 | | `exportReturn_ErrAudioEncoderConfiguration` | Error encountered configuring audio encoder. | 38 | | `exportReturn_ErrVideoEncoderConfiguration` | Error encountered configuring video encoder. | 39 | | `exportReturn_ErrInvalidPixelFormat` | Pixel format not compatible with output format. | 40 | | `exportReturn_ErrOutputBuffer` | Error creating output buffer. | 41 | | `exportReturn_ErrInputBuffer` | Error accessing input buffer. | 42 | | `exportReturn_ErrAudioEncoder` | Error encountered during audio encoding. | 43 | | `exportReturn_ErrVideoEncoder` | Error encountered during video encoding. | 44 | | `exportReturn_ErrMuxer` | Error encountered during muxing. | 45 | | `exportReturn_ErrVersion` | Error encountered because of versions. | 46 | | `exportReturn_ErrColorSpace` | Specified color space is not compatible with output format. | 47 | | `exportReturn_ErrVideoEncoderAdaptor` | Error encountered using video encoding adaptor. | 48 | | `exportReturn_ErrPixelBufferCreation` | Error creating pixel buffer. | 49 | | `exportReturn_ErrPixelBufferLock` | Error encountered locking buffer. | 50 | | `exportReturn_ErrPixelBufferPlanarFormat` | Error encountered with pixel buffer planar format. | 51 | | `exportReturn_ErrPixelBufferBytesMatch` | Error encountered with byte matching, within pixel buffer. | 52 | | `exportReturn_ErrPixelBufferUnlock` | Error encountered unlocking buffer. | 53 | | `exportReturn_ErrPixelBufferException` | Error encountered; exception accessing buffer. | 54 | | `exportReturn_ErrPixelBufferAppend` | Error appending to pixel buffer. | 55 | | `exportReturn_Unsupported` | Unsupported selector. | 56 | -------------------------------------------------------------------------------- /docs/intro/premiere-pro-plugin-types.md: -------------------------------------------------------------------------------- 1 | # Premiere Pro plugin Types 2 | 3 | | Type | Description | 4 | |-|-| 5 | | [Importers](../importers/importers.md) | Import video and audio media into Premiere. | 6 | | | Synthetic importers, a subset, dynamically synthesize media without creating an actual file on disk. | 7 | | | Custom importers, dynamically synthesize media to disk. | 8 | | [Export Controllers](../export-controllers/export-controllers.md) | Can drive any exporter to generate a file in any format and perform custom post-processing operations. | 9 | | | Developers wanting to integrate Premiere Pro with an asset management system will want to use this API instead of the exporter API. | 10 | | [Exporters](../exporters/exporters.md) | Allows the user to output media to disk. | 11 | | [Transmitters](../transmitters/transmitters.md) | Sends video, audio, and closed captioning to any external device during playback and editing. | 12 | | [Video Filters](../video-filters/video-filters.md) | **We strongly recommend using the After Effects SDK to develop effects plugins. Most of the effects included in Premiere Pro are After Effects plugins.** | 13 | | | Process a series of video frames with parameters that can be animated over time. | 14 | | [GPU Effects & Transitions](../gpu-effects-transitions/gpu-effects-transitions.md) | Process two video sources into a single destination over time. | 15 | | | This API is based on the After Effects API, with certain functions to enable transition functionality in Premiere Pro. | 16 | | [Control Surfaces](../control-surfaces/control-surfaces.md) | Interface with a hardware control surface to support audio mixing, basic transport controls, and the Lumetri Color panel. | 17 | | | The API supports two-way communication with Premiere Pro, so that motorized hardware faders, VU meters, etc can be in sync with the application. | 18 | 19 | ## Other Supported plugin Standards 20 | 21 | | Type | Description | 22 | |-|-| 23 | | Adobe After Effects API | Premiere Pro supports a portion of the AE API. The After Effects SDK is not included in the Premiere Pro SDK. The last chapter in the After Effects SDK Guide.pdf, included in the After Effects SDK, contains information on known differences with how Premiere Pro supports the AE API. | 24 | | VST | Starting in CC, Premiere supports version 3 of the VST specification for audio effects. | 25 | | | In CS6.x and previous versions, support was limited to version 2.4. | 26 | | ASIO | An ASIO driver is often provided in addition to a transmit plugin, to provide audio output during editing, playback, and Export To Tape. | 27 | | | Prior to CS6, an ASIO driver was required to support audio input for voiceover recording in the audio mixer. On macOS, a Core Audio component may be provided rather than an ASIO driver. | 28 | | Core Audio | macOS only. May be provided instead of an ASIO driver. | 29 | 30 | --- 31 | 32 | ### Plugin Support Across Adobe Video and Audio Applications 33 | 34 | This chart shows which third-party plugins are supported by the various Video and Audio applications. 35 | 36 | | | Premiere Pro | After Effects | Media Encoder | Audition | Character Animator | Prelude | 37 | | --------------------------- | ------------ | ------------- | ------------- | -------- | ------------------ | ------- | 38 | | After Effects AEGPs | | X | | | | | 39 | | After Effects effects | X | X | | | | | 40 | | After Effects transitions | X | | | | | | 41 | | ASIO | X | X | | X | | X | 42 | | Control Surfaces | X | | | X | | | 43 | | CoreAudio | X | X | | X | | X | 44 | | Premiere device controllers | X | | | | | | 45 | | Premiere export controllers | X | | | | | | 46 | | Premiere exporters | X | X | X | X | | | 47 | | Premiere importers | X | X | X | X | | X | 48 | | Premiere recorders | X | | | | | | 49 | | Premiere transmitters | X | X | | | X | X | 50 | | Premiere video filters | X | | | | | | 51 | | QuickTime codecs | X | X | X | X | | X | 52 | | Transitions | X | | | | | | 53 | | VfW codecs | X | X | X | X | | X | 54 | | VST audio effects | X | | | X | | | 55 | 56 | --- 57 | 58 | ### Premiere Elements Plugin Support 59 | 60 | Premiere Elements uses the same core libraries for plugin support that Premiere Pro does, although Premiere Elements is 32-bit, whereas Premiere Pro is 64-bit starting with CS5. 61 | 62 | | Premiere Elements version | Equivalent Premiere Pro API version | 63 | | ------------------------- | ----------------------------------- | 64 | | 12 | CS6 | 65 | | 11 | CS5.5 | 66 | | 10 | CS5.5 | 67 | | 9 | CS5 | 68 | | 8 | CS4 | 69 | 70 | It's always important to test the plugin fully in each application before advertising compatibility. 71 | 72 | Check out [Guidelines for Exporters in Premiere Elements](../exporters/additional-details.md#guidelines-for-exporters-in-premiere-elements) for instructions on how to set up your exporter to be used in Premiere Elements. 73 | 74 | --- 75 | 76 | ### What Exactly Is a Premiere Pro Plugin? 77 | 78 | Premiere plugins contain a single entry point of a type specific to each API. 79 | 80 | Plugins are DLLs on Windows, and Carbon or Cocoa Bundles on macOS. 81 | 82 | Plugins in the \\Plugins[language] folder, and any of its subfolders, will be loaded at launch. 83 | 84 | Plugins can have private resources. 85 | 86 | Only one plugin per file is parsed, unlike After Effects and Photoshop plugins, which can contain multiple entry points. 87 | -------------------------------------------------------------------------------- /docs/importers/return-codes.md: -------------------------------------------------------------------------------- 1 | # Return Codes 2 | 3 | | Return Code | Reason | 4 | |-|-| 5 | | `imNoErr` | Operation has completed without error. | 6 | | `imTooWide` | File dimensions too large. | 7 | | `imBadFile` | Bad file format. To defer an unsupported subtype to a lower priority importer, return this during `imOpenFile8` or `imGetInfo8`. | 8 | | `imUnsupported` | Unsupported selector. | 9 | | `imMemErr` | Memory error. | 10 | | `imOtherErr` | Unknown error. | 11 | | `imNoContent` | No audio or video. | 12 | | `imBadRate` | Bad audio rate. | 13 | | `imBadCompression` | Bad compression. | 14 | | `imBadCodec` | Codec not found. | 15 | | `imNotFlat` | Unflattened QuickTime movie. | 16 | | `imBadSndComp` | Bad sound compression. | 17 | | `imNoTimecode` | Timecode supported, but not found. | 18 | | `imMissingComponent` | Missing component needed to open the file. | 19 | | `imSaveErr` | Error saving file. | 20 | | `imDeleteErr` | Error deleting file. | 21 | | `imNotFoundErr` | The requested metadata chunk was not found. | 22 | | `imSetFile` | Return this from `imGetPrefs8` only if you are a custom importer and you need Premiere to alter it's file access information (e.g. a new path or filename is created). | 23 | | `imIterateStreams` | Return from `imGetInfo8` to indicate that there are more streams to describe. Premiere will send `imGetInfo8` for the next stream. | 24 | | `imBadStreamIndex` | Return from `imGetInfo8` after interating through streams to indicate that there are no more streams to describe. | 25 | | `imCantTrim` | Return from `imCheckTrim` if the file cannot be trimmed by the importer. | 26 | | `imDiskFull` | Return from `imTrimFile8` if there is not enough space to complete the trim operation. | 27 | | `imDiskErr` | Return from `imTrimFile8` if there is a general disk or I/O error during the trim operation. | 28 | | `imFileShareViolation` | Return from `imOpenFile8` if file cannot be opened due to another process having exclusive read access | 29 | | `imIterateFrameSizes` | Return from `imGetPreferredFrameSize`, to be called again to describe more frame sizes for a particular pixel format. | 30 | | `imMediaPending` | Return from `imGetSourceVideo` or `imCreateAsyncImporter` if the importer is still processing the file and cannot return video frames yet. | 31 | | `imDRMControlled` | Return from `imOpenFile8` if the file cannot be opened because it is under rights management. | 32 | | `imActivationFailed` | Activation of a component failed (usually due to user cancellation). This is used by Premiere Elements. | 33 | | `imFrameNotFound` | New in CS4. Return if an importer could not find the requested frame (typically used with async importers) | 34 | | `imBadHeader` | New in CS5. The file cannot be opened because of a header error | 35 | | `imUnsupportedCompression` | New in CS5. The file has a compression type that the importer does not support | 36 | | `imFileOpenFailed` | New in CS5. The importer was unable to open the file on disk | 37 | | `imFileHasNoImportableStreams` | New in CS5. The file has no audio or video stream | 38 | | `imFileReadFailed` | New in CS5. A read from an open file failed | 39 | | `imUnsupportedAudioFormat` | New in CS5. The importer cannot import something in the audio format | 40 | | `imUnsupportedVideoBitDepth` | New in CS5. The video bit depth of this file is unsupported by the importer | 41 | | `imDecompressionError` | New in CS5. The importer hit an error decompressing the audio or video | 42 | | `imInvalidPreferences` | New in CS5. Invalid prefs data was passed to the importer | 43 | | `inFileNotAvailable` | New in CS5. Return from `imQueryContentState` if the file/stream is no longer available because it is offline or deleted | 44 | | `imRequiresProtectedContent` | New in CS5.5. Return from `imInit` if the importer depends on a library that has not been activated yet. | 45 | | `imNoCaptions` | New in CC. Return from `imInitiateAsyncClosedCaptionScan` if the clip has no closed captions, or return from `imGetNextClosedCaption` when there are no more captions. | 46 | | `imCancel` | Return from `imGetPrefs8` if user cancels or the plugin cannot open the file (custom/synthetic importer). | 47 | | `imBadFormatIndex` | Return this when given an out of range format index, and from `imGetIndFormat` when plugin has no more formats to enumerate. | 48 | | `imIsCacheable` | Return from `imInit` if a plugin does not need to be called to initialize every time Premiere is launched. This will help reduce the time to launch the application. | 49 | -------------------------------------------------------------------------------- /docs/intro/plugin-installation.md: -------------------------------------------------------------------------------- 1 | # Plug In Installation 2 | 3 | Plugins must have an installer. This simplifies installation by the user, provides more compact distribution, and ensures all the pieces are installed correctly. 4 | 5 | Create a container folder for your plugin(s) to minimize user confusion. 6 | 7 | Don't unintentionally overwrite existing plugins, or replace newer versions. 8 | 9 | The installer should find the default installation directories as described below. 10 | 11 | It is also appreciated when an installer allows the user to specify an alternate directory. 12 | 13 | Plugins should be installed in the common plugin location. 14 | 15 | Supported Premiere and After Effects plugins installed here will be loaded by Premiere Pro, After Effects, Audition, and Media Encoder. 16 | 17 | Other plugin types, such as QuickTime and VfW codecs should be installed at the operating system level. 18 | 19 | --- 20 | 21 | ## Windows 22 | 23 | As of Premiere Pro version 22.0, the `\Plug-ins` directories have been renamed `\Plugins`, to better coincide with Apple's Human Interface Guidelines. Premiere Pro will continue to attempt to load plugins from `\Plug-Ins` directories as well, for the foreseeable future. 24 | 25 | Starting in CC, each version of Premiere Pro will create a unique registry key that provide locations of folders of interest for third-party installations for that version. 26 | 27 | For example, here are the registry values **for CC 2015.3:** 28 | 29 | Key: `HKEY_LOCAL_MACHINE/Software/Adobe/Premiere Pro/10.0/` 30 | 31 | Value name: `CommonPluginInstallPath` 32 | 33 | Value data: `C:\Program Files\Adobe\Common\Plugins\7.0\MediaCore\\` (or whatever the proper MediaCore plugins folder is; note that this is the same as what the After Effects installer provides for a corresponding registry key) 34 | 35 | Starting in CC 2015.3, **control surface plugins** should be installed here: 36 | 37 | `/Library/Application Support/Adobe/Common/Plugins/ControlSurface/` 38 | 39 | **For sequence presets:** 40 | 41 | Value name: `SequencePresetsPath` 42 | 43 | Value data: `[Adobe Premiere Pro installation path]\Settings\SequencePresets\` 44 | 45 | **For sequence preview presets:** 46 | 47 | Value name: `SequencePreviewPresetsPath` 48 | 49 | Value data: `[Adobe Premiere Pro installation path]\Settings\EncoderPresets\SequencePreview\` 50 | 51 | **For exporter presets:** 52 | 53 | Value name: `CommonExporterPresetsPath` 54 | 55 | Value data: **[User folder]AppDataRoamingAdobeCommonAME7.0Presets\** 56 | 57 | **Effects presets:** 58 | 59 | Value name: `PluginInstallPath` 60 | 61 | Value data: `[Adobe Premiere Pro installation path]\Adobe Premiere Pro\Plugins\Common` 62 | 63 | Third-party installers can start from this path, and then modify the string to build the path to the language-specific effect presets. 64 | 65 | **Prior to CC**, the only path given in the registry was the common plugin path for the most recently installed version of Premiere Pro: 66 | 67 | HKEY_LOCAL_MACHINE/Software/Adobe/Premiere Pro/CurrentVersion 68 | 69 | Value name: `Plug-InsDir` 70 | 71 | Value data: `REG_SZ` containing the full path of the plugin folder. 72 | 73 | As an example: `C:\Program Files\Adobe\Common\Plugins\7.0\MediaCore\` 74 | 75 | The best way to locate other preset folders was to start from the root path for Premiere Pro in the registry at 76 | 77 | `HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\App Paths\ Adobe Premiere Pro.exe`. 78 | 79 | Then, just add the proper subdirectories as described in the macOS section. 80 | 81 | --- 82 | 83 | ## macOS 84 | 85 | Starting in Premiere Pro version 22.0, The **common plugin location** is: 86 | 87 | `/Library/Application Support/Adobe/Common/Plugins/7.0/MediaCore/` 88 | 89 | Starting in CC 2015.3, **control surface plugins** should be installed here: 90 | 91 | `/Library/Application Support/Adobe/Common/Plugins/ControlSurface/` 92 | 93 | Previously, starting in CC 2015, Premiere Pro provided installer hints for Mac. You'll find `com.Adobe.Premiere Pro.paths.plist` at `/Library/Preferences`, which contains hints for your Mac installer to know where to install plugins, and is similar to the registry entries we have been providing on Win. 94 | 95 | The **common plugin location** was at: 96 | 97 | `/Library/Application Support/Adobe/Common/Plugins/7.0/MediaCore/` 98 | 99 | Starting in CC 2015.3, **control surface plugins** should be installed here: 100 | 101 | `/Library/Application Support/Adobe/Common/Plugins/ControlSurface/` 102 | 103 | Following OS X Code Signing guidelines, plugins should be installed in this separate shared location rather than in the application bundle. 104 | 105 | **For sequence presets:** 106 | 107 | `/Settings/SequencePresets/[Your specific folder]/` 108 | 109 | **Sequence preview presets:** 110 | 111 | `/Settings/EncoderPresets/SequencePreview/[Your editing mode GUID]/` 112 | 113 | **Encoder presets:** 114 | 115 | `/MediaIO/systempresets/[Your exporter folder]/` 116 | 117 | **Effects presets:** 118 | 119 | `/Plugins/[language subdirectory]/Effect Presets/` (see [Localization](localization.md) for the list of language codes) 120 | 121 | **Editing modes:** 122 | 123 | `/Settings/Editing Modes/` 124 | 125 | --- 126 | 127 | ## Plugin Naming Conventions 128 | 129 | On Windows, Premiere Pro plugins must have the file extension ".prm". On macOS, they have the file extension ".bundle". Other supported plugin standards use their conventional file extensions: ".aex" for After Effects plugins, ".dll" for VST plugins. 130 | 131 | While it is not required for your plugin to load, naming your plugins using the plugin type as a prefix (e.g. ImporterSDK, FilterSDK, etc.) will help reduce user confusion. 132 | 133 | --- 134 | 135 | ## Plugin Blocklisting (formerly Blacklisting) 136 | 137 | Specific plugins can be blocked from being loaded by MediaCore in specific applications, using blocklists. 138 | 139 | !!! note 140 | This does not work for After Effects plugins loaded by AE, although it does work for AE plugins loaded in Premiere Pro. 141 | 142 | In the plugins folder, look for the appropriate blacklist file, and append the the filename of the plugin to the file (e.g. BadPlugin, not BadPlugin.prm). If the file doesn't exist, create it first. "Blocklist.txt" contains names of plugins blacklisted from all apps. Plugins can be blocked from loading in specific apps by including them in "Blocklist Adobe Premiere Pro.txt", or "Blocklist After Effects.txt", etc. 143 | 144 | --- 145 | 146 | ## Creating Sequence Presets 147 | 148 | Not to be confused with encoder presets or sequence preview encoder presets, sequence presets are the successor to project presets. They contain the video, audio, timecode, and track layout information used when creating a new sequence. 149 | 150 | If you wish to add Sequence Presets for the New Sequence dialog, save the settings with a descriptive name and comment. Emulate our settings files. Install the presets as described in this section. 151 | 152 | --- 153 | 154 | ## Application-level Preferences 155 | 156 | For Windows 7 restricted user accounts, the only place that code has guaranteed write access to a folder is inside the user documents folder and its subfolders. 157 | 158 | ..Users[user name]AppDataRoamingAdobePremiere Pro[version]\\ 159 | 160 | This means that you cannot save data or documents in the application folder. There is currently no plugin API for storing preferences in the application prefs folder. Plugins can create their own preferences file in the user's Premiere prefs directory like so: 161 | 162 | ```cpp 163 | HRESULT herr = SHGetKnownFolderPath(FOLDERID_RoamingAppData, 0, NULL, preferencesPath); 164 | strcat(preferencesPath, "\\Adobe\\Premiere Pro\\[version]\\MyPlugin.preferences"); 165 | ``` 166 | 167 | On MacOS: `NSSearchPathForDirectoriesInDomains(NSApplicationSupportDirector y,NSLocalDomainMask,…)` 168 | 169 | This should get you started getting the Application Support folder which you can add onto to create something like: 170 | 171 | `/Library/Application Support/Adobe/Premiere Pro/[version]/MyPlugin.preferences` 172 | 173 | --- 174 | 175 | ## Dog Ears 176 | 177 | Premiere Pro's built-in player has a mode to display statistics, historically known as "dog ears", which can be useful in debugging and tuning performance of importers, effects, transitions, and transmitters. The statistics include frames per second, frames dropped during playback, pixel format rendered, render size, and field type being rendered. 178 | 179 | You can bring up the debug console in Premiere Pro. You can do this via Ctrl/Cmd-F12. To enable the dog ears, type this: 180 | 181 | ```cpp 182 | debug.set EnableDogEars=true 183 | ``` 184 | 185 | to disable, use this: 186 | 187 | ```cpp 188 | debug.set EnableDogEars=false 189 | ``` 190 | 191 | If the enter keystroke seems to go to the wrong panel, this is an intermittent panel focus problem. Click the Tools or Info panel before typing in the Console panel, and the enter key will be processed properly. 192 | 193 | Once enabled, the player displays the statistics as black text on a partially transparent background. This allows you to still see the underlying video (to some extent) and yet also read the text. When you turn off dog ears, the setting may not take effect until you switch or reopen your current sequence. 194 | 195 | !!! note 196 | If you are developing a transmitter, displaying dog ears will result in duplicate calls to PushVideo for the same frame. This happens because the player routinely updates the dog ears on a timer even when the frame hasn't changed for updated stats. As of CS6, this triggers a PushVideo to active transmitters as a side effect. 197 | -------------------------------------------------------------------------------- /docs/importers/whats-new.md: -------------------------------------------------------------------------------- 1 | # What's New 2 | 3 | ## What's New in Premiere Pro CC 2019 (13.0) 4 | 5 | We've begun adding colorspace support to Premiere Pro's APIs, beginning with Importers. 6 | 7 | Adding APIs `AddFrameToCacheWithColorSpace()` and `GetFrameFromCacheWithColorSpace()` which will deprecate `AddFrameToCacheWithColorProfile2()` and `GetFrameFromCacheWithColorProfile2()`. 8 | 9 | --- 10 | 11 | ## What's New in Premiere Pro CC 2014 12 | 13 | Importers can now choose the format they are rendering in, which allows importers to change pixel formats and quality based on criteria like enabled hardware and other Clip Source Settings, such as HDR. To handle the negotiation, implement `imSelectClipFrameDescriptor`. 14 | 15 | `imSourceVideoRec` now includes a quality attribute. [PPix Cache Suite](../universals/sweetpea-suites.md#ppix-cache-suite) is now at version 6, adding `AddFrameToCacheWithColorProfile2()` and `GetFrameFromCacheWithColorProfile2()`, which are the same as the ones added in version 5 with the addition of a PrRenderQuality parameter. 16 | 17 | `imFileInfoRec8.highMemUsage` is no longer supported. 18 | 19 | --- 20 | 21 | ## What's New in Premiere Pro CC October 2013 release? 22 | 23 | `imInitiateAsyncClosedCaptionScanRec` now provides extra fields for the importer to fill in the estimated duration of all the captions. This is useful for certain cases where the embedded captions contain many frames of empty data. 24 | 25 | --- 26 | 27 | ## What's New in Premiere Pro CC? 28 | 29 | Starting in CC, importers can support closed captioning that is embedded in the source media. Note that Premiere Pro can also import and export captions in a sidecar file (e.g. .mcc, .scc, or 30 | 31 | .xml) alongside any media file, regardless of the media file format. This does not require any specific work on the importer side. The importer only needs to add support if it will support embedded closed captions. 32 | 33 | Importers can now support audio beyond basic mono, stereo, and 5.1, without implementing multiple streams (existing importers do not need to be updated). The importer specifies a channel layout by implementing the new `imGetAudioChannelLayout` selector. Otherwise the channel layout will be assumed to be discrete. 34 | 35 | The clip preferences are now passed with `imIndPixelFormatRec`, so that an importer can choose to return varying pixel formats depending on the Clip Source Settings. 36 | 37 | --- 38 | 39 | ## What's New in Premiere Pro CS6.0.2? 40 | 41 | This release adds more support for growing files by adding a new flag, `imFileInfoRec8.mayBeGrowing`. 42 | 43 | --- 44 | 45 | ## What's New in Premiere Pro CS6? 46 | 47 | Importers can now bring in stereoscopic footage as a single clip with separate left and right channels. 48 | 49 | With some additional work, importers can now support growing files. The refresh rate for growing files is set by the user in Preferences > Media > Growing Files. The importer should get the refresh rate using the new call `GetGrowingFileRefreshInterval()` in the Importer File Manager Suite. Call `RefreshFileAsync()` to refresh the file. 50 | 51 | A new selector, `imQueryInputFileList`, was added to support Collect Files in After Effects for file types that use more than a single file. In imImportInfoRec, a new member, `canProvideFileList`, specifies whether the importer can provide a list of all files for a copy operation. If the importer does not implement this selector, the host will assume the media just uses a single file at the original imported media path. 52 | 53 | The Media Accelerator Suite is now at version 4. `FindPathInDatabaseAndValidateContentState` provides a new way to find existing media accelerators, making sure they are up-to-date. 54 | 55 | Importers can now choose whether or not they want to provide peak audio data on a clip-by-clip basis. 56 | 57 | The importer-wide setting still remains in `imImportInfoRec.canProvidePeakAudio`, but an importer can override the general setting by setting `imFileInfoRec8.canProvidePeakAudio` appropriately. 58 | 59 | --- 60 | 61 | ## What's New in Premiere Pro CS5.5? 62 | 63 | Importers can now support color management, when running in After Effects. The importer should set `imImageInfoRec.colorProfileSupport` to `imColorProfileSupport_Fixed`, and then describe the color profiles supported by the clip using the new `imGetIndColorProfile` selector. When importing the frame, specify the color profile in `imSourceVideoRec. selectedColorProfileName`. The [PPix Cache Suite](../universals/sweetpea-suites.md#ppix-cache-suite) has been updated to differentiate between color profiles as well. 64 | 65 | New `canProvidePeakAudio` flag to allow an importer to provide peak audio data by responding to `imGetPeakAudio`. 66 | 67 | The new return value, `imRequiresProtectedContent`, allows an importer to be disabled if a library it depends on has not been activated. 68 | 69 | --- 70 | 71 | ## What's New in Premiere Pro CS5? 72 | 73 | When an importer's settings dialog is opened, the importer now has access to the resolution, pixel aspect ratio, timebase, and audio sample rate of the source clip, in `imGetPrefsRec`. 74 | 75 | Custom importers can now use a new call in the Importer File Manager Suite, `RefreshFileAsync()`, to be able to update a clip after it is modified in `imGetPrefs8`. 76 | 77 | Two new selectors have been added. 78 | 79 | - `imQueryDestinationPath` allows importers that trim or copy files to be able to change the destination path of the trimmed or copy file. 80 | - `imQueryContentState` gives the host an alternate way of checking the state of a clip, for clips that have multiple source files. 81 | 82 | A new return value, `inFileNotAvailable` can be returned from `imQueryContentState` if the clip is no longer available because it is offline or has been deleted. 83 | 84 | As a convenience, when a file is opened, an importer can tell Premiere Pro how much memory to reserve for the importer's usage, rather than calling ReserveMemory in the [Memory Manager Suite](../universals/sweetpea-suites.md#memory-manager-suite). The importer should pass back this value in `imFileOpenRec8.outExtraMemoryUsage`. 85 | 86 | Several new return values are available for more descriptive error reporting: 87 | 88 | - `imBadHeader`, 89 | - `imUnsupportedCompression`, 90 | - `imFileOpenFailed`, 91 | - `imFileHasNoImportableStreams`, 92 | - `imFileReadFailed`, 93 | - `imUnsupportedAudioFormat`, 94 | - `imUnsupportedVideoBitDepth`, 95 | - `imDecompressionError`, and 96 | - `imInvalidPreferences` 97 | 98 | --- 99 | 100 | ## What's New in Premiere Pro CS4? 101 | 102 | For CS4 only, importers are loaded and called from a separate process. As a result of being in a separate process, (1) all importers must do their own file handling, (2) privateData is no 103 | 104 | longer accessible from `imGetPrefs8`, and (3) the compressed frame selectors such as `imGetCompressedFrame` are no longer supported (this may now be achieved using custom pixel formats and a renderer plugin). 105 | 106 | To debug importers, attach to the `ImporterProcessServer` process. There is also a separate Importer Process Plugin Loading.log. 107 | 108 | All legacy selectors have been removed, and are now longer supported. All structures used only in these legacy selectors have been removed as well. 109 | 110 | There are built-in XMP metadata handlers for known filetypes. These handlers write and read metadata to and from the file, without going through the importer. `imSetTimeInfo8` is no longer called, since this is set by the XMP handler for that filetype. 111 | 112 | All file-based importers (which does not include synthetics) are required to do their own file handling now, rather than having Premiere Pro open the files. The `imCallbackFuncs`: `OpenFileFunc` and `ReleaseFileFunc` are no longer supported. 113 | 114 | Due to the out-of-process importing, `privateData` is not accessible during `imGetPrefs8`, and has been removed from `imGetPrefsRec`. 115 | 116 | `imGetFrameInfo`, `imDisposeFrameInfo`, `imGetCompressedFrame`, and `imDisposeCompressedFrame` are no longer supported. Supporting a custom pixel format in an importer, a renderer, and an exporter is the new way to implement smart rendering, by passing custom compressed data from input to output. 117 | 118 | New `imFrameNotFound` return code. Returned if an importer could not find the requested frame (typically used with async importers). 119 | 120 | New in Premiere Pro 4.1, importer prefs are now part of imSourceVideoRec, passed to both `imGetSourceVideo` and the async import calls 121 | 122 | New in Premiere Pro 4.1, there is a new filepath member in imFileInfoRec8. For clips that have audio in files separate from the video file, set the filename here, so that UMIDs can properly be generated for AAFs. 123 | 124 | --- 125 | 126 | ## What's New in Premiere Pro CS3? 127 | 128 | Importers can specify an initial poster frame for a clip in imImageInfoRec. 129 | 130 | Importers can specify subtype names during the new `imGetSubTypeNames` selector. This selector is sent after each `imGetIndFormat`, which gives an importer the opportunity to enumerate all the fourCCs and display names (e.g. "Cinepak") of their known compression types for a specific filetype. The importer can return imUnsupported, or create an array of `imSubTypeDescriptionRec` records (pairs of fourCCs and codec name strings) for all the codecs/subtypes it knows about. 131 | 132 | Importers that open their own files should specify how many files they keep open between `imOpenFile8` and `imQuietFile` using the new Importer File Manager Suite, if the number is not equal to one. Importers that don't open their own files, or importers that only open a single file should not use this suite. Premiere's File Manager now keeps track of the number of files held open by importers, and limits the number open at a time by closing the least recently used files when too many are open. On Windows, this helps memory usage, but on MacOS this addresses a whole class of bugs that may occur when too many files are open. 133 | 134 | Importers can also specify that certain files have very high memory usage, by setting `imFileInfoRec8.highMemUsage`. The number of files allowed to be open with this flag set to true is currently capped at 5. 135 | 136 | Importers can now specify an arbitrary matte color for premultiplied alpha channels in `imImageInfoRec.matteColor`. Importers can state that they are uncertain about a clip's pixel aspect ratio, field type, or alpha info in imImageInfoRec.interpretationUncertain. 137 | 138 | The imInvalidHandleValue is now -1 for MacOS. 139 | 140 | Importers can specify a transform matrix for frames by setting `imImageInfoRec.canTransform = kPrTrue`, and then during `imImportImage`, when `imImportImageRec.applyTransform` is non-zero, use `imImportImageRec.transform`, and `destClipRect` to calculate the transform - This code path is currently not called by Premiere Pro. After Effects uses this call to import Flash video. 141 | 142 | New in Premiere Pro 3.1, the new capability flag, `imImportInfoRec.canSupplyMetadataClipName`, allows an importer to set the clip name from metadata, rather than the filename. The clip name should be set in `imFileInfoRec8.streamName`. This is useful for clips recorded by some new file-based cameras. 143 | 144 | New in Premiere Pro 3.1, the new `imGetFileAttributes` selector allows an importer to provide the clip creation date in the new imFileAttributesRec. 145 | --------------------------------------------------------------------------------