Add CameraServer feeds_updated signal, and document async behavior

[shiena]

fixed: #108136

• Add SafeFlag to prevent concurrent camera thread initialization
• Set monitoring_feeds to true only after device enumeration completes
• Document that monitoring_feeds requires waiting a few frames
• Add code examples for GDScript and C# showing proper usage pattern

This ensures camera feeds are properly initialized before being accessed and prevents potential crashes from concurrent thread creation.

[adamscott]

I think we should rework the API instead of documenting workarounds. (again, not directed to you @shiena)

[Ivorforce]

This isn't fully thread safe. But I'm noticing on reviewing SafeFlag that it's improperly implemented, and cannot be made truly thread safe. For the moment, this is probably fine. I'll address my SafeFlag concerns some other time.

[Ivorforce]

Looks good from my perspective now.
Thanks for doing all the adjustments!

This still needs a review from @godotengine/xr though.

[shiena]

There are two issues with this camera application:

• The CameraLinux::_update_devices function automatically updates the CameraFeed list, causing unnecessary background processing.
• When CameraLinux::set_monitoring_feeds is called with true, false, true in sequence, the CameraFeed list is not updated from the second call onwards.

@onready var reload = $ReloadButton
var current_feed: CameraFeed

func _ready():
	reload.pressed.connect(_on_pressed_reload)

func _on_pressed_reload():
	if CameraServer.monitoring_feeds:
		CameraServer.monitoring_feeds = false
		await get_tree().process_frame
	if not CameraServer.feeds_updated.is_connected(_on_feeds_updated):
		CameraServer.feeds_updated.connect(_on_feeds_updated)
	CameraServer.monitoring_feeds = true

func _on_feeds_updated():
	var feeds = CameraServer.feeds()
	if not feeds.is_empty():
		var current_feed = feeds[0]
		current_feed.frame_changed.connect(_on_frame_changed, ConnectFlag.CONNECT_DEFERRED | ConnectFlag.CONNECT_ONE_SHOT)

func _on_frame_changed():
	// processing camera images
	pass

Therefore, we want to update the CameraFeed list only when CameraLinux::set_monitoring_feeds is set to true, and clear the CameraFeed list when set to false. Is this approach acceptable?

[Ivorforce]

• The CameraLinux::_update_devices function automatically updates the CameraFeed list, causing unnecessary background processing.

This was already the case before the PR. I think it's out of scope to fix this (unless there's an easy solution).

• When CameraLinux::set_monitoring_feeds is called with true, false, true in sequence, the CameraFeed list is not updated from the second call onwards.

This is bad, that should definitely be fixed.

Therefore, we want to update the CameraFeed list only when CameraLinux::set_monitoring_feeds is set to true, and clear the CameraFeed list when set to false. Is this approach acceptable?

That would remove the Linux platform's ability to auto-update camera feeds altogether. I don't think this is an acceptable regression. The above bug with the true, false, true sequence should be fixed with the current background-updated implementation.

[shiena]

Understood. This PR will not address the true, false, true sequence issue.

[Ivorforce]

Understood. This PR will not address the true, false, true sequence issue.

If the issue exists on current master, this PR does not have to address it (though it would be good to). If you don't intend to, could you open an issue for it?

[shiena]

I have created an issue and a pull request here.

#108582
#108584

[m4gr3d]

Should the signal also be fired when all the feeds are removed?

[shiena]

cameraIds is a temporary variable within this function to receive camera IDs from ACameraManager_getCameraIdList(). ACameraManager_deleteCameraIdList() releases that variable. Since we updated the camera feed before that point, we need to emit the feeds_updated signal.

[Ivorforce]

Not sure if this answered @m4gr3d's question

[m4gr3d]

I also meant to update the string value to camera_feeds_updated since in code a user would do:

CameraServer.camera_feed_added.connect(...)
CameraServer.camera_feed_removed.connect(...)
CameraServer.camera_feeds_updated.connect(...)

[shiena]

Fixed the signal name. Also reverted the variable name back to the original.

[m4gr3d]

Looks good!

[Ivorforce]

Not sure if this answered @m4gr3d's question

[Ivorforce]

I had another look, changes look sensible to me. Good work!

To release managers: While this is a new feature, its addition facilitates the new CameraServer workflow (where feed monitoring has to be enabled manually). So I'd argue this is 4.5 material since it's addressing an issue with a 4.5 change.

[Repiteo]

Thanks!