Merge pull request #6 from aenhancers/colombo/update-for-22.0-release

Update scripting docs for After Effects 22.0 release

docs/conf.py

@@ -22,11 +22,11 @@ def setup(app):
 
 # General information about the project.
 project = u'After Effects Scripting Guide'
-copyright = u'1992-2012 Adobe Systems Incorporated'
+copyright = u'1992-2021 Adobe Systems Incorporated'
 author = u'Adobe Systems Incorporated'
 
-version = u'0.0.1'
-release = u'0.0.1'
+version = u'22.0.0'
+release = u'22.0.0'
 
 pygments_style = 'sphinx'
 

docs/general/application.rst

@@ -925,6 +925,31 @@ Nothing.
 
 ----
 
+.. _app.setMultiFrameRenderingConfig:
+
+app.setMultiFrameRenderingConfig()
+*********************************************
+
+``app.setMultiFrameRenderingConfig(mfr_on, max_cpu_perc)``
+
+**Description**
+
+Calling this function from a script will set the Multi-Frame Rendering configuration for the next render. 
+After execution of the script is complete, these settings will be reset to what was previously set in the UI. 
+
+**Parameters**
+
+================  ================================================================================================
+``mfr_on``        Boolean value. Set to ``true`` to enable Multi-Frame Rendering.
+``max_cpu_perc``  Value from 1-100 representing the maximum CPU percentage Multi-Frame Rendering should utilize. If ``mfr_on`` is set to ``false``, pass in 100.
+================  ================================================================================================
+
+**Returns**
+
+Nothing.
+
+----
+
 .. _app.setSavePreferencesOnQuit:
 
 app.setSavePreferencesOnQuit()

docs/general/project.rst

@@ -418,7 +418,7 @@ Project.revision
 
 The current revision of the project. Every user action increases the revision number. New project starts at revision 1.
 
-**Returns**
+**Type**
 
 Integer; the current revision version of the project; read-only.
 
@@ -921,6 +921,42 @@ Retrieves an item by its :ref:`Item ID <Item.id>`
 
 :ref:`Item`.
 
+----
+
+.. _Project.layerByID:
+
+Project.layerByID()
+*********************************************
+
+``app.project.layerByID(id)``
+
+**Description**
+
+Instance method on Project which, when given a valid ID value, returns the Layer object in the Project with that given ID.
+
+**Parameters**
+
+===========     ======================
+``id``          A non-negative integer representing the ID of the Layer to be retrieved from the Project.
+===========     ======================
+
+**Returns**
+
+:ref:`Layer` with the given ID if it exists on the project; otherwise null. Non-valid IDs will throw an exception stating that the input parameter is not an unsigned integer.
+
+**Example**
+
+.. code:: javascript
+
+   var firstComp = app.project.item(1);
+   var firstLayer = firstComp.layer(1);
+   var layerID = firstLayer.id;
+
+   if (app.project.layerByID(layerID) === firstLayer) {
+      alert("You can get the Layer from the ID!");
+   }
+
+
 ----
 
 .. _Project.reduceProject:

docs/introduction/changelog.rst

@@ -8,6 +8,23 @@ What's new and changed for scripting?
 
 ----
 
+.. _Changelog.22.0:
+
+`After Effects 22.0 <https://helpx.adobe.com/after-effects/using/whats-new.html>`_ (October 2021)
+************************************************************************************************************************************
+
+- Scripting methods added
+	- Added: :ref:`Layer.id`
+	- Added: :ref:`Project.layerByID`
+	- Added: :ref:`Property.essentialPropertySource`
+- Scripting Access to Render Queue Notifications
+    - Added: :ref:`RenderQueue.queueNotify` 
+    - Added: :ref:`RenderQueueItem.queueItemNotify`
+- Scripting Access to Multi-Frame Rendering, Maximum CPU Percentage Overrides
+    - Added: :ref:`app.setMultiFrameRenderingConfig`
+
+----
+
 .. _Changelog.18.0:
 
 `After Effects 18.0 <https://helpx.adobe.com/after-effects/using/whats-new/2021-2.html>`_ (March 2021)

docs/layers/avlayer.rst

@@ -771,6 +771,9 @@ The AVLayer needs to comply with the restrictions below in order to be treated a
 **Returns**
 
 Boolean.
+
+----
+
 .. _AVLayer.compPointToSource:
 
 AVLayer.compPointToSource()

docs/layers/layer.rst

@@ -103,6 +103,26 @@ Boolean; read-only.
 
 ----
 
+.. _Layer.id:
+
+Layer.id
+*********************************************
+
+``app.project.item(index).layer(index).id``
+
+**Description**
+
+Instance property on Layer which returns a unique and persistent identification number used internally to identify a Layer between sessions. 
+The value of the ID remains the same when the project is saved to a file and later reloaded. 
+However, when you import this project into another project, new IDs are assigned to all Layers in the imported project. 
+The ID is not displayed anywhere in the user interface..
+
+**Type**
+
+Integer; read-only.
+
+----
+
 .. _Layer.index:
 
 Layer.index

docs/properties/property.rst

@@ -228,6 +228,44 @@ Boolean; read/write.
 
 ----
 
+.. _Property.essentialPropertySource:
+
+Property.essentialPropertySource
+*********************************************
+
+``app.project.item(index).layer(index).essentialProperty.property(index).essentialPropertySource``
+
+**Description**
+
+Instance property on an Essential Property object which returns the original source Property which was used to create the Essential Property.
+
+**Type**
+
+Can be either:
+
+-  A read/write :ref:`Property`, in the case that the source object used to create the Essential Property was a Property
+-  A read/write :ref:`AVLayer`, in the case that the source object used to create the Essential Property was a Media Replacement Footage item
+-  Null if called on a non-Essential Property
+
+**Example**
+
+.. code:: javascript
+
+  var firstComp = app.project.item(1);
+  var opacityProp = firstComp.layer(1).property("Transform").property("Opacity");
+
+  opacityProp.addToMotionGraphicsTemplate(firstComp);
+
+  var secondComp = app.project.item(2);
+  secondComp.layers.add(firstComp);
+
+  var essentialOpacity = secondComp.layer(1).essentialProperty.property(1);
+  if (essentialOpacity.essentialPropertySource == opacityProp) {
+    alert("You can get the source Property from an Essential Property!");
+  }
+
+----
+
 .. _Property.expression:
 
 Property.expression

docs/renderqueue/renderqueue.rst

@@ -37,6 +37,24 @@ Boolean; read-only.
 
 ----
 
+.. _RenderQueue.queueNotify:
+
+RenderQueue.queueNotify
+*********************************************
+
+``app.project.renderQueue.queueNotify``
+
+**Description**
+
+Read or write the **Notify** property for the entire Render Queue. 
+This is exposed in the UI as a checkbox in the lower right corner of the Render Queue panel.
+
+**Type**
+
+Boolean; read/write.
+
+----
+
 .. _RenderQueue.items:
 
 RenderQueue.items

docs/renderqueue/renderqueueitem.rst

@@ -135,6 +135,25 @@ The collection of Output Modules for the item.
 
 ----
 
+.. _RenderQueueItem.queueItemNotify:
+
+RenderQueueItem.queueItemNotify
+*********************************************
+
+``app.project.renderQueue.item(index).queueItemNotify``
+
+**Description**
+
+Scripts can read and write the **Notify** checkbox for each individual item in the Render Queue. This is exposed in the UI as a checkbox next to each Render Queue item in the Notify column.
+
+This column is hidden by default and may need to be selected to be visible by right clicking on the Render Queue column headers and choosing Notify. 
+
+**Type**
+
+Boolean; read/write.
+
+----
+
 .. _RenderQueueItem.render:
 
 RenderQueueItem.render