From 84756b68e68c8a25b820a8c3dda01ec7f0a59353 Mon Sep 17 00:00:00 2001 From: Bastien Montagne Date: Fri, 6 May 2022 11:08:10 +0200 Subject: Add documentation about Image/ImBuf to python/RNA API. Related to T95616, the relationship between Image ID and ImBuf 'cached' buffers can be fairly confusing when using the RNA API. Reviewed By: campbellbarton, jbakker Differential Revision: https://developer.blender.org/D14833 --- doc/python_api/examples/bpy.types.Image.py | 47 ++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 doc/python_api/examples/bpy.types.Image.py (limited to 'doc/python_api') diff --git a/doc/python_api/examples/bpy.types.Image.py b/doc/python_api/examples/bpy.types.Image.py new file mode 100644 index 00000000000..715623f6f76 --- /dev/null +++ b/doc/python_api/examples/bpy.types.Image.py @@ -0,0 +1,47 @@ +""" +Image Data +++++++++++ + +The Image data-block is a shallow wrapper around image or video file(s) +(on disk, as packed data, or generated). + +All actual data like the pixel buffer, size, resolution etc. is +cached in an :class:`imbuf.types.ImBuf` image buffer (or several buffers +in some cases, like UDIM textures, multi-views, animations...). + +Several properties and functions of the Image data-block are then actually +using/modifying its image buffer, and not the Image data-block itself. + +.. warning:: + + One key limitation is that image buffers are not shared between different + Image data-blocks, and they are not duplicated when copying an image. + + So until a modified image buffer is saved on disk, duplicating its Image + data-block will not propagate the underlying buffer changes to the new Image. + + +This example script generates an Image data-block with a given size, +change its first pixel, rescale it, and duplicates the image. + +The duplicated image still has the same size and colors as the original image +at its creation, all editing in the original image's buffer is 'lost' in its copy. +""" + +import bpy + +image_src = bpy.data.images.new('src', 1024, 102) +print(image_src.size) +print(image_src.pixels[0:4]) + +image_src.scale(1024, 720) +image_src.pixels[0:4] = (0.5, 0.5, 0.5, 0.5) +image_src.update() +print(image_src.size) +print(image_src.pixels[0:4]) + +image_dest = image_src.copy() +image_dest.update() +print(image_dest.size) +print(image_dest.pixels[0:4]) + -- cgit v1.2.3