Desired Premult.

[revisionfx]

Standard Change Workflow

• Create proposal as issue (you're doing this now!)
• Tag this issue with standard change tag
• Identify subcommittee: at least one plug-in vendor, and at least one host
• Discuss the idea in this issue
• Write new or updated code
• Publish updates as a pull request on a feature/PROPOSAL-NAME branch
  • Make sure that PR references this issue number to keep them in sync
  • Discuss and review code in the PR
• When subcommittee signs off and other members don't have any further review comments,
  maintainer merges PR to master which closes PR and issue

Requirements for accepting a standard change:

• Header files updated
• Documentation updated
• Release notes added
• Compatibility review completed
• Working code demonstrated with at least one host and one plugin
• At least two members sign off
• No further changes requested from membership

Summary

Add a new plugin property that hosts can set to suggest that effects should premultiply their output.

Motivation

The standard currently has premult properties for input clips; however there is no way for the host to communicate to a generator plugin, or a plugin taking only an opaque or RGB input, whether it should premultiply its output or not.

Explanation

This effect property allows an effect generating alpha to know whether to output premult or straight alpha. If the input is ImageOpaque or the effect's type is Generator it can't use its input(s) to know this.

The value is only advisory; the effect may or may not check this property and may in any case create output clips of any premultiplication state.

Effects using this property should still tag their outputs with the correct premultiplication state.

The property is set on the image effect's effect instance.

Context

This property, when set by the host, should be set during the following calls:

• kOfxImageEffectActionBeginSequenceRender
• kOfxImageEffectActionRender
• kOfxImageEffectActionEndSequenceRender

Valid Values

• kOfxImagePreMultiplied
• kOfxImageUnPreMultiplied

Documentation Impact

• Should be added to the Programming Guide in the discussion of premult.
• Should be added to the Programming Reference in the discussion of premult, and in the section oin the properties valid on an effect instance.

see pull request #62: Desired Premult

[fxtech]

Could we take advantage of the current set of properties? What if the host sets kOfxImageEffectPropPreMultiplication on the output clip to specify its desired premul output. The plugin can read this and obey it, but is still allowed to change it.

[revisionfx]

This is meant as a global flag sort of.

TRUE there is a read-write for output in doc in kOfxImageEffectActionGetClipPreferences
During render these properties are read-only

https://openfx.readthedocs.io/en/doc/Reference/ofxImageEffectActions.html#group__ImageEffectActions_1gae66560a2d269b17e160613adf22fd7d0

"This should be called once after creation of an instance, each time an input clip is changed, and whenever a parameter named in the kOfxImageEffectPropClipPreferencesSlaveParam has its value changed. "
//
This is meant even when we create instance, now I have a premult boolean checkbox in many tools, would check if TRUE or FALSE based on this flag and even hide the checkbox if this property is supported.

Unless I was putting a bunch of code to calculate this in clip preferences action I would likely just set output if input is Opaque to DesiredPremult. There could be a doc note added for ClipPreferences about that, yes.

[revisionfx]

Ok here's my suggestion

We add a cross reference in doc/comments for the ClipPreferences kOfxImageEffectPropPreMultiplication the premultiplication of the output clip

whereby if DesiredPremult prop is supported (status == 0) then host is expected to set DesiredPremult on output clip. Plugin can over-write back to Opaque. Only in that circumstance then an host can safely carry-on Opaque further down than direct imported source images or conversion from 3 channels to 4 for plugin. This way it's safe, does not potentially break anything (turns undefined into a bug) as there is conditional on a new property being supported.

Nothing in the API specs envision an host would be responsible to convert a plugin setting Straight to Premult... i.e. Plugins are expected to handle both cases. We are just making sure which case is perfectly clear.

Pierre