Add a method to render targets and cameras to retrieve a Metal texture

[srmainwaring]

🎉 New feature

Relates to: #461 and discussions in #422. It accompanies PR #463 but does not depend upon it.

Summary

This PR provides access to the underlying Metal texture object. The functions MetalId() and RenderTextureMetalId()
provide the Metal equivalent of GLId() and RenderTextureGLId() for OpenGL.

The functions expect a parameter void* _texturePtr which is the address of a pointer to void* as the object required for Metal is an Objective-C type id<MTLTexture> which we do not want exposed in the interface (the type is the id for an object
that implements the MTLTexture protocol).

Note: the functions do not add a dependency on Objective-C to the ignition rendering libraries, but they are intended to be used in Objective-C code as follows:

void *textureIdPtr = nullptr;
texture->RenderTextureMetalId(&textureIdPtr);
id<MTLTexture> metalTexture = CFBridgingRelease(textureIdPtr);

The translation unit containing the code should be compiled with ARC enabled and will need to link against the AppKit and Metal frameworks. When using cmake this is accomplished by CMakeLists.txt entries such as:

target_link_libraries(simple_demo_qml_metal PUBLIC
    ${IGNITION-RENDERING_LIBRARIES}
    ${OGRE2_LIBRARIES}
    ${OPENGL_LIBRARIES}
    Qt5::Core
    Qt5::Gui
    Qt5::Qml
    Qt5::Quick
    "-framework AppKit"
    "-framework Metal"
)

# Enable ARC on selected source files
set_source_files_properties(
    IgnitionRenderer.mm
    RenderThread.mm
    ThreadRenderer.mm
    PROPERTIES
    COMPILE_FLAGS
        "-fobjc-arc"
)

There is a runtime dependency on an upstream change to ogre-next: OGRECave/ogre-next@3b11873. Note that this PR does not require the upstream change to build as the Ogre interface used, getCustomAttribute, is available on the base class Ogre::TextureGpu and is used by the OpenGL functions.

Test it

These changes have no impact on existing functionality using the OpenGL render system.

To test these functions requires a version of ogre-next v2-2 that includes the change OGRECave/ogre-next@3b11873.

There is work in progress to enable the use of Metal for the example simple_demo_qml and for ign-gui and ign-gazebo. They depend upon this PR and provide a means to test the changes:

https://github.com/srmainwaring/ign-rendering/tree/feature/ign-rendering6-metal-simple_demo_qml
https://github.com/srmainwaring/ign-gui/tree/feature/ign-gui7-metal
https://github.com/srmainwaring/ign-gazebo/tree/feature/ign-gazebo7-metal

For more detail see comment: #463 (comment)

Checklist

• Signed all commits for DCO
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• codecheck passed (See contributing)
• All tests passed (See test coverage) *
• While waiting for a review on your PR, please help review another open pull request to support the maintainers

• A number of tests fail on macOS - these are unrelated to this PR:

91% tests passed, 9 tests failed out of 102

Total Test time (real) = 138.35 sec

The following tests FAILED:
	 19 - UNIT_Heightmap_TEST (SEGFAULT)
	 59 - UNIT_RenderingIface_TEST (SEGFAULT)
	 83 - INTEGRATION_depth_camera (Failed)
	 85 - INTEGRATION_camera (Failed)
	 87 - INTEGRATION_render_pass (Failed)
	 89 - INTEGRATION_shadows (Failed)
	 93 - INTEGRATION_segmentation_camera (Failed)
	 95 - INTEGRATION_sky (Failed)
	 97 - INTEGRATION_thermal_camera (Failed)

Note to maintainers: Remember to use Squash-Merge

[ahcorde]

This is breaking ABI, you should target main, isn't it @iche033 ?

[srmainwaring]

This is breaking ABI, you should target main, isn't it @iche033 ?

You're right - I'll update the PR accordingly.

Closing in lieu of #478 which is based on main