Light.GetLights() - Is this undocumented function safe to use?

There's an undocumented static function

Light[] Light.GetLights(LightType type, int layer)

. From my tests so far, the

layer

parameter doesn't actually appear to do anything. I can set it to any arbitrary value, and it always returns every light in the scene irrespective of layer. It returns a managed array, which is unfortunate as I would like to use it every frame, but the allocation is probably acceptably small.

I'm a bit wary of using this function which is undocumented, and seems to be broken with regards to the layer parameter. I don't actually need to distinguish between layers so the apparent behaviour is fine, but the brokenness is a concern. I'm building something which I would like to be forward compatible, and I have no idea whether this function is here to stay.

Has anybody used it? Does anyone know what's going on with the layer parameter? Is it going to break unpredictably under some circumstance I haven't tested? Is it undocumented for good reason?

 

is this method working on Android ? having trouble with it i think

 

Huh, sounds like it is not working! If you use something undocumented, don't be surprised when it stops working. If it is documented, go to the documentation and make sure you're using it properly.

 

Good point.

I confirm it's broken on Android/Vulkan (returns no light).

 

It would be nice to get a Unity staff reply to confirm the status of this function - should the brokenness be considered a bug? I might report it as a bug at some point to get it officially looked at.

 

I put a todo in our tasks thing, should be easy / not that long to make repro project. but i wont do it for layers.

 

Not sure how you would consider an undocumented feature to be a bug.

 

Well it's exposed in the public API in a fairly prominent place. If you find it in Intellisense as I did, it's not obvious that it's maybe not meant to work - it's only when you try it and find problems then research it that the situation becomes apparent. I think that something about this situation should change. Maybe it should be removed or marked as deprecated, or maybe it should be fixed to work reliably. It's even possible that missing documentation is actually an error.

 

I've never used it, but I wouldn't be surprised if it only exists for use by lighting explorer. If so, it is probably working as intended. (lighting explorer is editor only, so no need to implement functionality on Android, and the lighting explorer version doesn't take a layer parameter)

https://docs.unity3d.com/2020.2/Doc...faultLightingExplorerExtension.GetLights.html

You can certainly file a bug report to complain about an unnecessarily messy API though, even if this is the case. Maybe they will look into it.