Examples and tutorial on using rendering API from plugins

[chapulina]

Builds on top of #595

---

Add 2 example plugins and a tutorial explaining how they work. See tutorial for more context.

I had to link to some Dome APIs because we don't have Edifice APIs deployed yet.

Here are the example plugins at work, the server one sets a random color every 2 simulation seconds, and the GUI one sets a new random color when the button is clicked.

[chapulina]

@osrf-jenkins run tests please

[adlarkin]

The tutorial itself is great, thanks for doing this! One main question/concern I have is that the tutorial doesn't seem to discuss when or why one should use server/GUI rendering plugins instead of adding to SceneManager, RenderUtils, or Scene3D. Perhaps we can add comments about this to the tutorial? I am assuming that the reasons for using server/GUI rendering plugins are along the lines of the following:

• Performance (users only use what they need)
• Maintenance/code cleanliness/testability

[chapulina]

the tutorial doesn't seem to discuss when or why one should use server/GUI rendering plugins instead of adding to SceneManager, RenderUtils, or Scene3D

I'm giving this some thought.

The short answer is that we don't need to mention this to external users, because they can't modify those classes from their code.

We've been doing this as maintainers, but that doesn't scale, because we can't support every use case in the same plugin at the same time. That's why we have a plugin architecture, so users can implement functionality that's specific to their needs without modifying the core code. This to me is the biggest reason to keep everything in separate plugins, a lot of the functionality we ship should be as optional as user's plugins.

[adlarkin]

This to me is the biggest reason to keep everything in separate plugins, a lot of the functionality we ship should be as optional as user's plugins.

Agreed; perhaps we should consider refactoring SceneManager, RenderUtils, and Scene3D in the future to make better use of plugins. I am not sure how much work this would require, though (I'm guessing it would be a large task).

[codecov]

Codecov Report

Merging #596 (2856793) into main (8f1f44f) will decrease coverage by 0.04%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main     #596      +/-   ##
==========================================
- Coverage   77.43%   77.38%   -0.05%     
==========================================
  Files         212      212              
  Lines       12016    12016              
==========================================
- Hits         9304     9299       -5     
- Misses       2712     2717       +5     

Impacted Files	Coverage Δ
src/SimulationRunner.cc	92.76% <0.00%> (-1.09%)	⬇️
src/Server.cc	83.43% <0.00%> (+0.63%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 8f1f44f...2856793. Read the comment docs.