Document not to access image data during a step. (cyberbotics#5859)

* Document not to access image data during a step.

* Fix formatting.

Author: brettle

docs/reference/camera.md

@@ -133,7 +133,9 @@ The pixel information can be obtained from the `wb_camera_get_image` function.
 The red, green and blue channels (RGB) can be extracted from the resulting image by the `wb_camera_image_get_*`-like functions.
 
 Each time a camera is refreshed, an OpenGL rendering is performed, and the color information is copied into the buffer returned by the `wb_camera_get_image` function.
-The format of this buffers is BGRA (32 bits).
+The contents of the buffer are subject to change between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`.
+As a result, if you want to access the buffer during a step, you should copy it before the step begins and access the copy.
+The format of this buffer is BGRA (32 bits).
 We recommend to use the `wb_camera_image_get_*`-like functions to access the buffer because the internal format could change.
 
 > **Note** [MATLAB]: The MATLAB API uses a language-specific representation of color images consisting of a 3D array of RGB triplets.
@@ -912,6 +914,8 @@ byte_size = camera_width * camera_height * 4
 ```
 
 Attempting to read outside the bounds of this chunk will cause an error.
+The contents of the image are subject to change between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`.
+As a result, if you want to access the image during a step, you should copy it before the step begins and access the copy.
 Internal pixel format of the buffer is BGRA (32 bits).
 Note that the Java API uses little-endian format and stores the pixel integer value in ARGB format.
 
@@ -1098,6 +1102,9 @@ The `quality` parameter should be in the range 1 (worst quality) to 100 (best qu
 Low quality JPEG files will use less disk space.
 For PNG images, the `quality` parameter is ignored.
 
+`wb_camera_save_image` should not be called between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`,
+because the image is subject to change during that period.
+
 The return value of the `wb_camera_save_image` function is 0 in case of success.
 It is -1 in case of failure (unable to open the specified file or unrecognized image file extension).
 

docs/reference/lidar.md

@@ -489,14 +489,17 @@ range = wb_lidar_get_layer_range_image(tag, layer)
 
 ##### Description
 
-*get the range image and range image associate with a specific layer*
+*get the range image and range image associated with a specific layer*
 
 The `wb_lidar_get_range_image` function allows the user to read the contents of the last range image grabbed by a lidar.
+It should not be called if the lidar was in point cloud mode during the most recent step.
 The range image is computed using the depth buffer produced by the OpenGL rendering.
 The range image is coded as an array of single precision floating point values corresponding to the range value of each pixel of the image.
 The precision of the lidar values decreases when the objects are located farther from the near clipping plane.
 Pixels are stored in scan lines running from left to right and from first to last layer.
 The memory chunk returned by this function shall not be freed, as it is managed by the lidar internally.
+The contents of the image are subject to change between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`.
+As a result, if you want to access the image during a step, you should copy it before the step begins and access the copy.
 The size in bytes of the range image can be computed as follows:
 
 ```
@@ -604,6 +607,7 @@ number_of_points = wb_lidar_get_number_of_points(tag)
 *get the points array, points array associate with a specific layer and total number of point*
 
 The `wb_lidar_get_point_cloud` function returns the pointer to the point cloud array, each point consists of a [`WbLidarPoint`](#wblidarpoint).
+It should not be called unless the lidar was in point cloud mode during the most recent step.
 The memory chunk returned by this function shall not be freed, as it is managed by the lidar internally.
 The size in bytes of the point cloud can be computed as follows:
 
@@ -612,6 +616,8 @@ size = lidar_number_of_points * sizeof(WbLidarPoint)
 ```
 
 Attempting to read outside the bounds of this memory chunk will cause an error.
+The contents of the point cloud are subject to change between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`.
+As a result, if you want to access the point cloud during a step, you should copy it before the step begins and access the copy.
 
 The `wb_lidar_get_layer_point_cloud` function is a convenient way of getting directly the sub point cloud associated with one layer.
 

docs/reference/rangefinder.md

@@ -545,6 +545,8 @@ The range image is coded as an array of single precision floating point values c
 The precision of the range-finder values decreases when the objects are located farther from the near clipping plane.
 Pixels are stored in scan lines running from left to right and from top to bottom.
 The memory chunk returned by this function shall not be freed, as it is managed by the range-finder internally.
+The contents of the image are subject to change between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`.
+As a result, if you want to access the image during a step, you should copy it before the step begins and access the copy.
 The size in bytes of the range image can be computed as follows:
 
 ```
@@ -666,5 +668,7 @@ HDR images are saved as 32-bit floating-point single-channel images.
 For PNG and JPEG, depth data is stored in the range `0` to `255`.
 This depth data can thus be extracted for further use by reading the image file.
 
+`wb_range_finder_save_image` should not be called between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`, because the image is subject to change during that period.
+
 The return value of the `wb_range_finder_save_image` function is 0 in case of success.
 It is -1 in case of failure (unable to open the specified file or unrecognized image file extension).

docs/reference/robot.md

@@ -265,6 +265,8 @@ You can simply call them before `wb_robot_step_begin` or after `wb_robot_step_en
 However, some of these functions can be called between `wb_robot_step_begin` and `wb_robot_step_end` if you enable the supervisor tracking feature.
 `wb_supervisor_field_enable_sf_tracking`, `wb_supervisor_node_enable_pose_tracking` and `wb_supervisor_node_enable_contact_point_tracking` force Webots to continuously stream the requested information to the controller.
 By enabling the tracking, the corresponding supervisor functions can be called between `wb_robot_step_begin` and `wb_robot_step_end`, because their value will be queried to Webots during `wb_robot_step_begin` and received during `wb_robot_step_end`.
+Also, note that the data returned by the following functions are subject to change between a call to `wb_robot_step_begin` and the subsequent call to `wb_robot_step_end`: `wb_camera_get_image`, `wb_camera_recognition_get_segmentation_image`, `wb_lidar_get_range_image`, `wb_lidar_get_layer_range_image`, `wb_lidar_get_point_cloud`, `wb_lidar_get_layer_point_cloud`, and `wb_range_finder_get_range_image`.
+As a result, if you want to access that data during a step, you should copy it before the step begins and access the copy.
 
 The C API has two additional functions: `wb_robot_init` and `wb_robot_cleanup`.
 There is no equivalent of the `wb_robot_init` and `wb_robot_cleanup` functions in the Java, Python, C++ and MATLAB APIs.