Require hosts to call Instance Changed action after loading a project

[garyo]

Open Effects Proposal for Standard Change

Please read the contribution guidelines first.

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 and doc
• Publish updates as a pull request (ideally 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
  • Meet all requirements below for accepting 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

Currently a host may or may not call instanceChanged after loading a saved project. This means plugins do not get an opportunity to update the enabled status of params or take other actions based on the input clips and/or param values. This proposal would require conforming hosts to call kOfxActionInstanceChanged after loading a project containing OpenFX plugin instances. This call would be with type=kOfxTypeClip. kOfxTypeParameter would also make sense but I suggest we just use Clip, and plugins can do whatever they need to.

As for kOfxPropChangeReason, should we recomend kOfxChangeUserEdited since loading a project is a user-initiated action? We could add a new reason, kOfxChangeProjectLoaded if that is needed, to distinguish these events from others, but since some hosts are already doing this, I don't think we need to make them change their behavior.

Motivation

Without this, plugins can't set their param enabledness or some overlay features because nothing is called after createInstance. A plugin has no way to know it's been updated (clip connected, params modified) after the instance was created.

Problem

This would enable plugins to show proper param status after a project is loaded.

Impact

This should have no impact on existing plugins, since some hosts already call instanceChanged after loading a project, and a plugin should respond to instanceChanged whenever it happens.

It does impact hosts, because any conforming host will need to make this call, if it doesn't already.

Documentation Impact

This is primarily (or entirely) a documentation/standard change. No change to the existing API.

Stakeholders

Both plugins and hosts will benefit from this by improving UI behavior.

Discussion

[revisionfx]

• removing, linking to wrong one :)

[garyo]

You could merge #180 with this

I'm not sure how that's related -- can you say more, @revisionfx ?

[garyo]

Thinking more about this issue, I notice that instanceChanged can't get source images either. Would it make sense to create some way to get a clip's image dimensions at the current time in instanceChanged? Thoughts, anyone?

[revisionfx]

What I was saying - we can't place initially position 2D param based on image dimension without adding a button ask user to press so we can get a UI callback to set that.

[barretpj]

Thinking more about this issue, I notice that instanceChanged can't get source images either.

It's highly impractical for clipGetImage() to be allowed - that's generally an expensive operation, unsuitable for this action.

Would it make sense to create some way to get a clip's image dimensions at the current time in instanceChanged? Thoughts, anyone?

Do you mean permitting clipGetRegionOfDefinition()? That's probably viable.

[garyo]

Thinking more about this issue, I notice that instanceChanged can't get source images either.
...
Do you mean permitting clipGetRegionOfDefinition()? That's probably viable.

Ah, great idea, @barretpj . Yes, that would work for me (and maybe it's already working to call that from within instanceChanged; I don't know). I know OpenFX allows clip images to vary in size over time, and this would support that (since it takes the current time) without having to actually compute the image pixels.

@revisionfx would that work for you?

[revisionfx]

yes, parsing notes

"in Baselight the Source clip is disconnected during actionCreateInstance()"
"crash in Nuke before 12.6"

[barretpj]

I'm not saying clipGetRegionOfDefinition() would work during instanceChanged in Baselight. Certainly during createInstance() it would be very unlikely to work.

[Guido-assim]

In Assimilate Scratch we call InstanceChanged when an input clip is connected. When CreateInstance is called the clips are not connected.

[garyo-gpsw]

Per discussion in the TSC meeting: this proposal will require hosts to call instanceChanged with reason=clip when a clip is connected, even if the clip connection is the result of loading a project.
It will also mandate that clipGetRegionOfDefinition must work in instanceChanged, though perhaps it already does.

[MrKepzie]

Just for curiosity, if instanceChanged is called when loading a project right after creating the plug-in, and that instanceChanged in turns set other parameter values (e.g: a Choice parameter value that controls the value of other parameters. For example a Preset choice controlling a Double2D, but then user can set keyframes on that Double2D, the preset just serves as initialization).
In this scenario, the plug-in probably doesn't want to update the other parameters because it may override the keyframes.

I was always assuming (maybe it's not written anywhere, I don't remember) that the createInstanceAction must be called after loading all parameter values, so that the plug-in can restore enabledness and other states there.

If you impose the host to call instanceChanged when loading a parameter, this implies 2 things:

• createInstanceChanged will no longer be called after loading parameter values (I know of some plug-ins that expect things to be set already)
• the plug-in has no way (that I can see) to distinguish between instanceChanged called as a result of user action vs project loading action.

Maybe add a ProjectLoadingReason so that the plug-in can ignore if necessary ?

[bruno-j-nicoletti]

That's how I originally meant it to work. Calling 'instancedChanged' on each parameter when you load a plugin can cause all sorts of weirdnesses for more complex plugins as you mention. "createInstance" was meant to be called after all the parameter values were loaded and the plugin does what it needs to with the state of the plugin.

…

On Mon, 14 Apr 2025 at 09:47, Alexandre Gauthier ***@***.***> wrote: Just for curiosity, if instanceChanged is called when loading a project right after creating the plug-in, and that instanceChanged in turns set other parameter values (e.g: a Choice parameter value that controls the value of other parameters. For example a Preset choice controlling a Double2D, but then user can set keyframes on that Double2D, the preset just serves as initialization). In this scenario, the plug-in probably doesn't want to update the other parameters because it may override the keyframes. I was always assuming (maybe it's not written anywhere, I don't remember) that the createInstanceAction must be called *after* loading all parameter values, so that the plug-in can restore enabledness and other states there. If you impose the host to call instanceChanged when loading a parameter, this implies 2 things: - createInstanceChanged will no longer be called after loading parameter values (I know of some plug-ins that expect things to be set already) - the plug-in has no way (that I can see) to distinguish between instanceChanged called as a result of user action vs project loading action. Maybe add a ProjectLoadingReason so that the plug-in can ignore if necessary ? — Reply to this email directly, view it on GitHub <#184 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOIGQAQM27I77VFWNWFDIT2ZNY2XAVCNFSM6AAAAAB2BNYU42VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMBQHEYTMNBTGA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***> *MrKepzie* left a comment (AcademySoftwareFoundation/openfx#184) <#184 (comment)> Just for curiosity, if instanceChanged is called when loading a project right after creating the plug-in, and that instanceChanged in turns set other parameter values (e.g: a Choice parameter value that controls the value of other parameters. For example a Preset choice controlling a Double2D, but then user can set keyframes on that Double2D, the preset just serves as initialization). In this scenario, the plug-in probably doesn't want to update the other parameters because it may override the keyframes. I was always assuming (maybe it's not written anywhere, I don't remember) that the createInstanceAction must be called *after* loading all parameter values, so that the plug-in can restore enabledness and other states there. If you impose the host to call instanceChanged when loading a parameter, this implies 2 things: - createInstanceChanged will no longer be called after loading parameter values (I know of some plug-ins that expect things to be set already) - the plug-in has no way (that I can see) to distinguish between instanceChanged called as a result of user action vs project loading action. Maybe add a ProjectLoadingReason so that the plug-in can ignore if necessary ? — Reply to this email directly, view it on GitHub <#184 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAOIGQAQM27I77VFWNWFDIT2ZNY2XAVCNFSM6AAAAAB2BNYU42VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDQMBQHEYTMNBTGA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[garyo]

"createInstance" was meant to be called after all the parameter values were loaded and the plugin does what it needs to with the state of the plugin.

Yes, but this is about clips. At least in some hosts (see above, and also Resolve) the inputs are not connected at createInstance time -- at least that's my understanding. When a saved project is loaded, at least in those hosts, the input is silently connected but no instanceChanged action is called. (And I'm not sure If the plugin param enabled state depends on the input clips in any way (dimensions, color space, etc.) the plugin doesn't hear about its input clip til the user changes something else.

My use case would also be satisfied if the spec would guarantee that when loading a saved project, any input clips are connected before the host calls createInstance, and that clipGetRegionOfDefinition (and other clip properties) works on those clips in createInstance (as well as setting kOfxParamPropEnabled of course).

[MrKepzie]

Then I would say it's just a specification issue for the host implementation. These mentionned hosts should conform to it.
Calling createInstanceAction wthout having clips connected is bound to bring trouble anyway as the plug-in is in an intermediate undefined state that cannot rely on any clip state.

Also a side discussion which belongs to another issue anyway, but I never really like the idea of Clip vs Parameter. I prefer having Clips being just Image Parameters, as it makes things much trivial to maintain and reason, especially for nodal graphs: the "input" of a clip/parameter can be e.g: a parameter link to another parameter in the host (many hosts have a concept of parameter linking) or e.g: an "expression" (or function) that generates a value for this parameter.
I saw in another issue that people started so suggest having "Camera" suite behaving like clips... which to me feels wrong as it is just another type of parameter with a different type of data.