Add procedure handler based API

tytan652 commented 6 months ago

Description

[!WARNING]
~Not meant to be used by third-party, if they do it's at their own risk as if it's an unstable API.~

I would like some feedback before stating that it can be used by third-party.

Supersedes https://github.com/obsproject/obs-studio/pull/5679
Supersedes https://github.com/obsproject/obs-studio/pull/7638

Relies on:

https://github.com/obsproject/obs-studio/pull/10100

Adds a procedure handler that enables the use of obs-browser feature (only panels now) outside of the plugin itself without having to rely on symbols search inside the plugin file.

TODO:

[x] Rename classes with a better namespace
[x] Make the interface a installable header-only library with a CMake package

Motivation and Context

Inspired by how obs-websocket did its API and by the fact that implementing an browser API in the frontend-api looks more and more like a bad idea. I made a procedure handler based API for obs-browser.

Related to the wish to split service integration from the UI as plugins, but this is not strictly bond to services.

How Has This Been Tested?

Branch that replace make the whole UI use the new API which enables to test all the API: https://github.com/tytan652/obs-studio/pull/21
- Integrations needs to be tested to test all API functions…
Header installation needs to be checked for Windows and macOS.
- Tested on Windows, --component Development adds the header

Types of changes

New feature (non-breaking change which adds functionality)

Checklist:

[x] My code has been run through clang-format.
[x] I have read the contributing document.
[x] My code is not on the master branch.
[x] The code has been tested.
- Me alone is not enough to test that
[x] All commit messages are properly formatted and commits squashed where appropriate.
[x] I have included updates to all appropriate documentation.

PatTheMav commented 5 months ago

I think the approach is correct and barring some concerns regarding the name (PhQCefWidget is a mouthful, OBSBrowserWidget would be more expressive, especially if this becomes a public API).

As for the API - how can we make this API available as part of obs-frontend-api without also exposing obs-browser publicly?

Because plugins need to be built out-of-tree, the browser API functions need to be available via the frontend API only, so it needs to be exposed there and needs to be compiled and linked without the browser plugin present.

tytan652 commented 5 months ago

As for the API - how can we make this API available as part of obs-frontend-api without also exposing obs-browser publicly?

This design is meant to make it unrelated to obs-frontend-api (beside obs-browser internals using it).

…the browser API functions need to be available via the frontend API only…

This API does not need/depend on the frontend API.

PatTheMav commented 5 months ago

As for the API - how can we make this API available as part of obs-frontend-api without also exposing obs-browser publicly?

This design is meant to make it unrelated to obs-frontend-api (beside obs-browser internal using it).

…the browser API functions need to be available via the frontend API only…

This API does not need/depend on the frontend API.

Got it. In that case this PR cannot supersede the PRs mentioned in the OP - the goal of at least one of those is to allow external plugins to create and manage their own browser docks.

As those plugins only link with libobs and obs-frontend-api, such functionality would need to be made available in the latter.

I still think it's worthwhile to have an API for internal use that does not require internal knowledge of the obs-browser plugin to interact with panels, but it's not solving the use case for external plugins then.

tytan652 commented 5 months ago

Got it. In that case this PR cannot supersede the PRs mentioned in the OP - the goal of at least one of those is to allow external plugins to create and manage their own browser docks.

Beside the native flag issue, because of the QCefWidget in a window/dock without the native flag can go wrong. This API can be used with the dock-related front-end API to make docks with a QCefWidget.

PatTheMav commented 5 months ago

Got it. In that case this PR cannot supersede the PRs mentioned in the OP - the goal of at least one of those is to allow external plugins to create and manage their own browser docks.

Beside the native flag issue. This API can be used with the dock-related front-end API to make docks with a QCefWidget.

So with this merged, a leaner frontend API can be based on it you mean?

tytan652 commented 5 months ago

So with this merged, a leaner frontend API can be based on it you mean?

No need for new frontend API.

Plugins creates everything to have a PhQCefWidget instance
Use obs_frontend_add_dock_by_id("test", "Test", ph_qcef_widget.qwidget())
A dock with browser widget is created

Like I said earlier, there is an because of the missing native flag but it's inside the Frontend API that the issue should be solved.

Edit: I have made this https://github.com/tytan652/obs-studio/commit/5ef1362ada511f6ed62e3a4aa5c6dd0b663e58f1 in the past to fix the flag issue which rely to put a custom property in the given widget which is checked by the frontend API. This flag thing is a nightmare.

PatTheMav commented 5 months ago

So with this merged, a leaner frontend API can be based on it you mean?

No need for new frontend API.

Plugins creates everything to have a PhQCefWidget instance

Use obs_frontend_add_dock_by_id("test", "Test", ph_qcef_widget.qwidget())

A dock with browser widget is created

Like I said earlier, there is an because of the missing native flag but it's inside the Frontend API that the issue should be solved.

How can a plugin do that without access to the PhQCefWidget class? A plugin needs to be able to do that without access to obs-browser. Or is that just a string identifier and the plugin needs to throw around a void pointer?

tytan652 commented 5 months ago

How can a plugin do that without access to the PhQCefWidget class? A plugin needs to be able to do that without access to obs-browser. Or is that just a string identifier and the plugin needs to throw around a void pointer?

The API header (with PhCef* classes) is "public", no change in CMake was made to install it for now.

PatTheMav commented 5 months ago

How can a plugin do that without access to the PhQCefWidget class? A plugin needs to be able to do that without access to obs-browser. Or is that just a string identifier and the plugin needs to throw around a void pointer?

The header with PhCef* classes is "public", no change in CMake was made to install it for now.

That's what I was hinting at - obs-browser is not allowed to install headers. Only libobs and obs-frontend-api are. If PhCef* needs to be made available, it needs to happen in obs-frontend-api. No other module is allowed to expose anything to plugins.

tytan652 commented 5 months ago

The header is not part of the obs-browser CMake module, for now it's a standalone interface.

PatTheMav commented 5 months ago

The header is not part of the obs-browser CMake module, for now it's a standalone interface.

Ah my bad - that header is not part of this PR then but would be added in an associated obs-studio PR?

tytan652 commented 5 months ago

Ah my bad - that header is not part of this PR then but would be added in an associated obs-studio PR?

lib/obs-browser-api.hpp is the header, it is in the PR and the API is made with procedure handler to avoid being dependent of the module. But obs-browser needs the header to have the API version macro.

tytan652 commented 5 months ago

The API header is now installed with other OBS Studio headers and I changed the namespace of the API classes (Ph-->OBSBrowser).

Edit: Sorry I made a typo it was "now" not "not".

tytan652 commented 5 months ago

Update CMake part to match https://github.com/obsproject/obs-websocket/pull/1196 CMake as Pat approved it, like I said there https://github.com/obsproject/obs-websocket/pull/1196#discussion_r1468463474.

obsproject / obs-browser