Fix Python Display.imageNew and improve documentation

[stefaniapedrazzi]

Address #2441: improve documentation of the image format returned by the Camera API and how to display a Camera image in a Display.

Tasks:

• specify image format in Camera section
• add examples in Display section
• add a warning in the Python API if the passed image has string format
  edit: fix free of invalid pointer in the Python API if the passed image has string format

[stefaniapedrazzi]

I could finally identify the error causing the crash when passing a string image data to the Python Camera.imageNew function.
The problem is that the string is freed but it should not (malloc is only executed in case of a list type):

webots/resources/languages/python/controller.i

Lines 414 to 416 in fb5cd3d

	%typemap(freearg) const void * {
	free($1);
	}

I'm checking but I'm not sure if there is a way to recognize if the const void * argument has been created from a list (with malloc) or from a string (no free required).

[stefaniapedrazzi]

The wb_camera_get_image returns data in BGRA format.
But to work correctly I have to set the wb_display_image_new format to ARGB.
This doesn't seem very intuitive for users.

[stefaniapedrazzi]

The inversion comes from this line:

webots/src/Controller/api/display.c

Line 751 in fb5cd3d

((uint32_t *)i->image)[j] = img[j * 4] << 24 | img[j * 4 + 1] << 16 | img[j * 4 + 2] << 8 | img[j * 4 + 3];

For wb_camera_get_image input data in BGRA format the image pixel uint32_t is 0xbbggrraa.
But it seems that internally it is stored in little-endian because accessing the image bytes you get inversed values and inversed bytes are sent to Webots (here).

printf("pixel %02x %02x %02x %02x\n", ((unsigned char *)(i->image))[0], ((unsigned char *)(i->image))[1], ((unsigned char *)(i->image))[2], ((unsigned char *)(i->image))[3]);
# result for pixel data B=152(0x98) G=109(0x6d) R=90(0x5a) A=255(0xff)
# "pixel ff 5a 6d 98"

I fixed it locally and run the test suite and all the tests are still working correctly.
But I would fix this on the develop branch to prevent issues with user controllers.

[omichel]

It looks good to me. I just have a few minor suggestions.
We shall now fix the develop branch with respect to the ARGB format.

[omichel]

Thank you.