Method SetTransformAsync
- Namespace
- OBSStudioClient.Model
- Assembly
- OBSClient.dll
SetTransformAsync(SceneItemTransformUpdate, CancellationToken)
Changes the transform of the scene item (its position, scale, rotation, alignment, bounds and crop), and returns when OBS Studio has made the change, and when the model shows it if it follows the transforms.
public Task SetTransformAsync(SceneItemTransformUpdate update, CancellationToken cancellationToken = default)Parameters
updateSceneItemTransformUpdateWhat to change: only the members that are set are sent, and OBS Studio leaves every other member as it is. Start from ToUpdate() to change what is there.
cancellationTokenCancellationTokenA token that ends the wait. A change that was not sent yet is not sent.
Returns
- Task
A task that completes when Transform shows the change (when the model follows the transforms), or when OBS Studio has answered (when it does not).
Remarks
OBS Studio makes the change in steps that it announces one by one (a change of the crop together with another comes as two events), and the call waits until Transform has all of it. When the model does not follow the transforms there is nothing of it to wait for: the call returns when OBS Studio has answered. The change itself is one request, which OBS Studio makes as a whole.
OBS Studio 33.0.0 announces a crop only for a scene that it renders (the program scene, the preview scene of studio mode, a scene that a projector shows): for another scene it announces the crop when the scene is rendered. A model that follows the transforms therefore reads the scene again after a change that sets a crop, instead of waiting for an announcement that may not come.
See SetEnabledAsync(bool, CancellationToken) for the order of changes and the wait.
Exceptions
- ArgumentNullException
updateis null.- ArgumentException
updatesets no member (IsEmpty): OBS Studio refuses that.- ObsRemovedException
The scene item, or its scene, was removed.
- ObsNotConnectedException
There is no connection to OBS Studio. Nothing was changed.
- ObsNotReadyException
OBS Studio is changing its scene collection, or did so after the call. Nothing was changed.
- ObsUnknownOutcomeException
OBS Studio did not answer in time, or the connection ended: it is not known whether it made the change.
- ObsNotConfirmedException
OBS Studio made the change, and the model does not show it: the events did not show it in time, and the model could not be read again in time. Do not send the change again.
- ObsResponseException
OBS Studio refused the change: a rotation above 360 degrees, a crop below 0, or a bounds width or height below 1 (the bounds of a transform without bounds are left out of ToUpdate() for that reason).