Expose the relative-coordinate migration to Desktop

[aleksandr-voitenko]

The ultimate goal of the task is:

Enable safe base canvas resolution changes in settings by introducing relative scene coordinates across obs-studio, obs-studio-node, and desktop, preserving the visual layout of shared horizontal/vertical scene graph.

Description

This is the OSN part of a three-repository change:

1. obs-studio implements canvas-aware relative transforms and crop references.
   Enable canvas-aware relative scene coordinates obs-studio#764
2. obs-studio-node exposes the native lifecycle and metadata.
3. desktop migrates collections and applies Base Resolution changes transactionally.
   Scene collections: migrate layouts to relative coordinates desktop#6100

The components must ship as a matched set.

The components must ship as a matched set because scene-item and crop IPC payloads have changed.

Relative-coordinate contract

• Relative scene coordinates are an invariant of this OSN generation. OSN explicitly sets AbsoluteCoordinates=false during global OBS initialization, before any public, private, or group scene graph is created.
• Callers cannot select an absolute-coordinate runtime mode.
• Public scene-item transform getters and setters remain expressed in absolute canvas pixels; libobs performs the internal relative conversion.
• SceneFactory.invalidateItemTransformCache() invalidates cached position, scale, and crop values after a Base Canvas reset. It does not mutate transforms itself; subsequent access reads the effective absolute values from libobs.

Legacy absolute scene-collection migration and Base Resolution transactions remain Desktop responsibilities.

Canvas assignment and routing

• Scene.add() now exposes the existing optional canvas argument:

  add(source: IInput, transform?: ISceneItemInfo, video?: IVideo): ISceneItem;

• When provided, the canvas is assigned before the initial transform is applied.

• Providing a canvas requires a transform.

• When the canvas is omitted or undefined, the item remains unassigned and renders on every canvas.

• addItems() likewise creates initially unassigned items.

• ISceneItem.video now returns IVideo | null; null represents all-canvas routing. The setter accepts a live IVideo, but does not currently accept null to unassign an existing item.

• Assigning an item to another canvas preserves its caller-visible position, scale, bounds, and crop.

• Invalid or destroyed canvas handles are rejected without leaving a partially created scene item.

• A shared osn::common::INVALID_ID value represents a missing OSN object reference instead of incorrectly treating the real canvas ID 0 as “unassigned.”

• Scene::AddSource validates its IPC request shape before reading transform fields.

Canvas lifetime

Video.destroy() now reports native removal outcomes accurately:

• A canvas assigned to one or more scene items cannot be destroyed. The call throws and the canvas object remains valid so the caller can reassign or remove those items and retry.
• Active video also rejects removal without invalidating the canvas.
• If removal completes but the remaining video contexts cannot be initialized, the removed canvas is already invalid.
• Successful destruction invalidates the OSN wrapper.

Nested-scene crop references

• ICropInfo can include referenceWidth and referenceHeight.
• The pair records the nested-scene dimensions against which the crop was authored.
• Crop references travel through item creation, getters, setters, canvas assignment, and native scene save/load.
• OSN reads back the effective reference because libobs may normalize or automatically establish it.
• Ordinary input crops remain source-pixel crops and do not expose reference dimensions.

Additional fixes

• Added the missing blendingMethod declaration to ISceneItemInfo.
• Fixed the bounds setter, which previously read the existing bounds without calling obs_sceneitem_set_bounds().
• Added cropToBounds to ITransformInfo and exposed it as an individual scene-item property.
• Initialized the complete native aggregate transform structure before applying it.
• Position, scale, and crop setters now respect dirty cache flags and do not suppress writes based on stale values.
• Canvas assignment and aggregate transform updates invalidate affected scene-item caches.
• Preserved signed crop values instead of wrapping negative IPC values into unsigned integers.

Breaking API changes

OBS initialization

OBS_API_initAPI no longer accepts positional arguments. It now requires exactly one options object:

OBS_API_initAPI({
  language,
  appDataPath,
  version,
  crashServerUrl,
});

All four fields are required strings. Pass an empty crashServerUrl to use the built-in endpoint for the current release channel.

Scene and transform types

• IScene.add() exposes the optional video parameter.
• ISceneItem.video now has a nullable getter.
• ISceneItemInfo requires blendingMethod.
• ITransformInfo requires cropToBounds.
• Nested-scene ICropInfo values may include referenceWidth and referenceHeight.

How Has This Been Tested?

Manual + Automated tests, Windows only.

Types of changes

• Breaking change (fix or feature that would cause existing functionality to change)