Add Projector

[iche033]

🎉 New feature

Summary

Add support for Projectors - an object that projects a texture onto a surface.

In order to get this new feature in gz-rendering7 in an ABI compatible way, I introduced a new SceneExt class that provides a generic CreateExt function for creating a Projector object.

• The proper way is to add CreateProjector virtual function in base class and override them in ogre 1.x and 2.x implementation which changes vtable and so breaks ABI. I have added all these functions but they are commented out with a todo not to uncomment them when forward porting to gz-rendering8

Key implementation details:

• The ogre 1.x implementation is ported from gazebo-classic's Projector class. It uses ogre material projective texturing feature.
  • in addition, I extended the implementation to support visibility flags so that we can toggle the visibility of the projected texture based on the camera's visibility mask.
• The ogre 2.x implementation uses screen space decals (instead of projective texturing) and has a different behavior.
  • Also added support for setting visibility flags.
  • Note: There is one major caveat with this implementation. The projection is not in the form of a "frustum" (i.e. projection becomes larger at longer distance). It uses ogre 2.x screen space decals. Think of a as a rectangular volume and any surface that intersects with the volume will have the texture mapped onto it.
  • We will need to investigate whether it's possible to change the implementation to match the ogre 1.x behavior in the future. Here is a related ogre forum post asking the same question. I will create an issue to track this limitation once the PR is merged.

The screenshot below illustrates the difference between ogre 1.x and ogre 2.x:

ogre 1.x: Projection based on a frustum (blue box is the projector)

ogre 2.x: Projection based on a rectangular volume

Test it

Run the UNIT_Projector_TEST and INTEGRATION_projector tests

e.g. testing with ogre 2.x

GZ_ENGINE_TO_TEST=ogre2 ./bin/UNIT_Projector_TEST
GZ_ENGINE_TO_TEST=ogre2 ./bin/INTEGRATION_projector

Build and run the projector demo

# build the demo
cd examples/projector
mkdir build
cd build
cmake ..
make

# Run the demo with ogre 1.x
./projector ogre

# Run the demo with ogre 2.x
./projector ogre2

Checklist

• Signed all commits for DCO
• Added tests
• Added example and/or tutorial
• Updated documentation (as needed)
• Updated migration guide (as needed)
• Consider updating Python bindings (if the library has them)
• 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

Note to maintainers: Remember to use Squash-Merge and edit the commit message to match the pull request summary while retaining Signed-off-by messages.

[codecov]

Codecov Report

Merging #845 (b523c27) into gz-rendering7 (7dc64e5) will increase coverage by 0.04%.
The diff coverage is 80.10%.

❗ Current head b523c27 differs from pull request most recent head b4a27fa. Consider uploading reports for the commit b4a27fa to get more accurate results

@@                Coverage Diff                @@
##           gz-rendering7     #845      +/-   ##
=================================================
+ Coverage          77.09%   77.14%   +0.04%     
=================================================
  Files                164      169       +5     
  Lines              14521    14712     +191     
=================================================
+ Hits               11195    11349     +154     
- Misses              3326     3363      +37     

Impacted Files	Coverage Δ
include/gz/rendering/Scene.hh	0.00% <ø> (ø)
include/gz/rendering/base/BaseScene.hh	0.00% <ø> (ø)
src/base/BaseScene.cc	89.10% <ø> (ø)
include/gz/rendering/base/SceneExt.hh	66.66% <66.66%> (ø)
ogre2/src/Ogre2Projector.cc	71.42% <71.42%> (ø)
src/Scene.cc	87.50% <87.50%> (ø)
ogre2/src/Ogre2Scene.cc	81.72% <96.00%> (+0.56%)	⬆️
include/gz/rendering/Projector.hh	100.00% <100.00%> (ø)
include/gz/rendering/base/BaseProjector.hh	100.00% <100.00%> (ø)
ogre2/src/Ogre2Material.cc	76.54% <100.00%> (+0.10%)	⬆️

... and 1 file with indirect coverage changes

[ahcorde]

Some minor comments, otherwise LGTM

[nkoenig]

Just minor comments

[nkoenig]

Suggested change

	/// \brief Get the camera's far clipping plane distance
	/// \brief Get the projector's far clipping plane distance

[iche033]

fixed. b4a27fa

[nkoenig]

Just minor comments

[ahcorde]

are all these windows failures expected ? https://build.osrfoundation.org/job/ign_rendering-pr-win/3223/

[iche033]

are all these windows failures expected ? https://build.osrfoundation.org/job/ign_rendering-pr-win/3223/

yes unfortunately tests started failing recently on the new ec2 windows machines. I think @j-rivero is looking into it.