Add information about the new LASER plugin to the Smode docs

[mitchmindtree]

Smode provides some nice docs under the "help" section - it would be nice if users could also find information about how to use the LASER plugin here. We already have extensive documentation throughout the API about what different parameters mean and how they behave (included in the generated smode_laser.h) so it should be easy enough to translate this over to the help docs.

[francis-maes]

absolutely!
Our documentation is written in a home-made XML format.
For the moment, the documentation is in a separate repository and cannot be extended on a per-plugin basis. But we know that this is an issue, and maybe we have here the first opportunity in order to push per-plugin extensible documentation on our side.

[mitchmindtree]

Extensive comment documentation can be found throughout the smode_laser.h and NannouLaserDevice.h files, but we probably care most about the behaviour of the parameters exposed on the LASER device GUI. Here are the 6 device parameters documented within smode_laser.h:

/// Update the `blank_delay_points` field of the interpolation configuration. This represents the
/// number of points to insert at the end of a blank to account for light modulator delay.
///
/// The value will be updated on the laser thread prior to requesting the next frame.
///
/// Returns `true` on success or `false` if the communication channel was closed.
bool frame_stream_set_blank_delay_points(const FrameStream *stream, uint32_t points);

/// Update the `distance_per_point` field of the interpolation configuration used within the
/// optimisation pass for frames. This represents the minimum distance the interpolator can travel
/// along an edge before a new point is required.
///
/// The value will be updated on the laser thread prior to requesting the next frame.
///
/// Returns `true` on success or `false` if the communication channel was closed.
bool frame_stream_set_distance_per_point(const FrameStream *stream, float distance_per_point);

/// Update the rate at which the stream will attempt to present images via the DAC. This value is
/// used in combination with the DAC's `point_hz` in order to determine how many points should be
/// used to draw each frame. E.g.
///
/// ```ignore
/// let points_per_frame = point_hz / frame_hz;
/// ```
///
/// This is simply used as a minimum value. E.g. if some very simple geometry is submitted, this
/// allows the DAC to spend more time creating the path for the image. However, if complex geometry
/// is submitted that would require more than the ideal `points_per_frame`, the DAC may not be able
/// to achieve the desired `frame_hz` when drawing the path while also taking the
/// `distance_per_point` and `radians_per_point` into consideration.
///
/// The value will be updated on the laser thread prior to requesting the next frame.
///
/// Returns `true` on success or `false` if the communication channel was closed.
bool frame_stream_set_frame_hz(const FrameStream *stream, uint32_t frame_hz);

/// The maximum latency specified as a number of points.
///
/// Each time the laser indicates its "fullness", the raw stream will request enough points
/// from the render function to fill the DAC buffer up to `latency_points`.
///
/// This value should be no greaterthan the DAC's `buffer_capacity`.
///
/// Returns `true` on success or `false` if the communication channel was closed.
bool frame_stream_set_latency_points(const FrameStream *stream, uint32_t points);

/// Update the rate at which the DAC should process points per second.
///
/// This value should be no greater than the detected DAC's `max_point_hz`.
///
/// By default this value is `stream::DEFAULT_POINT_HZ`.
///
/// Returns `true` on success or `false` if the communication channel was closed.
bool frame_stream_set_point_hz(const FrameStream *stream, uint32_t point_hz);

/// Update the `radians_per_point` field of the interpolation configuration. This represents the
/// amount of delay to add based on the angle of the corner in radians.
///
/// The value will be updated on the laser thread prior to requesting the next frame.
///
/// Returns `true` on success or `false` if the communication channel was closed.
bool frame_stream_set_radians_per_point(const FrameStream *stream, float radians_per_point);

It might also be useful to include some of the information provided in the nannou_laser README, in particular some information about some of the kinds of optimisations that are applied.

Another thing that comes to mind that might be worth mentioning is to remind the user to adjust the aspect ratio of the compo to match the aspect ratio of their LASER projector output (e.g. 1:1 in most cases). If the user fails to do this, the output from the LASER projector will appear skewed, as points are submitted within a normalised range from -1.0 to 1.0.

Of course, feel free to @ us when you have a way for 3rd party plugins to self-document and we will be happy to assist further 👍