Add support for tiled images and the UDIM naming scheme

This patch contains the work that I did during my week at the Code Quest - adding support for tiled images to Blender.

With this patch, images now contain a list of tiles. By default, this just contains one tile, but if the source type is set to Tiled, the user can add additional tiles. When acquiring an ImBuf, the tile to be loaded is specified in the ImageUser.
Therefore, code that is not yet aware of tiles will just access the default tile as usual.

The filenames of the additional tiles are derived from the original filename according to the UDIM naming scheme - the filename contains an index that is calculated as (1001 + 10*<y coordinate of the tile> + <x coordinate of the tile>), where the x coordinate never goes above 9.
Internally, the various tiles are stored in a cache just like sequences. When acquired for the first time, the code will try to load the corresponding file from disk. Alternatively, a new operator can be used to initialize the tile similar to the New Image operator.

The following features are supported so far:
- Automatic detection and loading of all tiles when opening the first tile (1001)
- Saving all tiles
- Adding and removing tiles
- Filling tiles with generated images
- Drawing all tiles in the Image Editor
- Viewing a tiled grid even if no image is selected
- Rendering tiled images in Eevee
- Rendering tiled images in Cycles (in SVM mode)
- Automatically skipping loading of unused tiles in Cycles
- 2D texture painting (also across tiles)
- 3D texture painting (also across tiles, only limitation: individual faces can not cross tile borders)
- Assigning custom labels to individual tiles (drawn in the Image Editor instead of the ID)
- Different resolutions between tiles

There still are some missing features that will be added later (see T72390):
- Workbench engine support
- Packing/Unpacking support
- Baking support
- Cycles OSL support
- many other Blender features that rely on images

Thanks to Brecht for the review and to all who tested the intermediate versions!

Differential Revision: https://developer.blender.org/D3509

4 files changed, 226 insertions, 14 deletions

diff --git a/source/blender/makesrna/intern/rna_image.c b/source/blender/makesrna/intern/rna_image.c
index 517bd2b7276..7a03bdb952b 100644
--- a/source/blender/makesrna/intern/rna_image.c
+++ b/source/blender/makesrna/intern/rna_image.c
@@ -57,6 +57,7 @@ static const EnumPropertyItem image_source_items[] = {
     {IMA_SRC_MOVIE, "MOVIE", 0, "Movie", "Movie file"},
     {IMA_SRC_GENERATED, "GENERATED", 0, "Generated", "Generated image"},
     {IMA_SRC_VIEWER, "VIEWER", 0, "Viewer", "Compositing node viewer"},
+    {IMA_SRC_TILED, "TILED", 0, "Tiled", "Tiled image texture"},
     {0, NULL, 0, NULL, NULL},
 };
 
@@ -209,6 +210,7 @@ static const EnumPropertyItem *rna_Image_source_itemf(bContext *UNUSED(C),
     RNA_enum_items_add_value(&item, &totitem, image_source_items, IMA_SRC_SEQUENCE);
     RNA_enum_items_add_value(&item, &totitem, image_source_items, IMA_SRC_MOVIE);
     RNA_enum_items_add_value(&item, &totitem, image_source_items, IMA_SRC_GENERATED);
+    RNA_enum_items_add_value(&item, &totitem, image_source_items, IMA_SRC_TILED);
   }
 
   RNA_enum_item_end(&item, &totitem);
@@ -238,6 +240,87 @@ static void rna_Image_file_format_set(PointerRNA *ptr, int value)
   }
 }
 
+static void rna_UDIMTile_label_get(PointerRNA *ptr, char *value)
+{
+  ImageTile *tile = (ImageTile *)ptr->data;
+  Image *image = (Image *)ptr->owner_id;
+
+  /* We don't know the length of the target string here, so we assume
+   * that it has been allocated according to what rna_UDIMTile_label_length returned. */
+  BKE_image_get_tile_label(image, tile, value, sizeof(tile->label));
+}
+
+static int rna_UDIMTile_label_length(PointerRNA *ptr)
+{
+  ImageTile *tile = (ImageTile *)ptr->data;
+  Image *image = (Image *)ptr->owner_id;
+
+  char label[sizeof(tile->label)];
+  BKE_image_get_tile_label(image, tile, label, sizeof(label));
+
+  return strlen(label);
+}
+
+static void rna_UDIMTile_tile_number_set(PointerRNA *ptr, int value)
+{
+  ImageTile *tile = (ImageTile *)ptr->data;
+  Image *image = (Image *)ptr->owner_id;
+
+  /* The index of the first tile can't be changed. */
+  if (tile->tile_number == 1001) {
+    return;
+  }
+
+  /* Check that no other tile already has that number. */
+  ImageTile *cur_tile = BKE_image_get_tile(image, value);
+  if (cur_tile == NULL || cur_tile == tile) {
+    tile->tile_number = value;
+  }
+}
+
+static int rna_Image_active_tile_index_get(PointerRNA *ptr)
+{
+  Image *image = (Image *)ptr->data;
+  return image->active_tile_index;
+}
+
+static void rna_Image_active_tile_index_set(PointerRNA *ptr, int value)
+{
+  Image *image = (Image *)ptr->data;
+  int num_tiles = BLI_listbase_count(&image->tiles);
+
+  image->active_tile_index = min_ii(value, num_tiles - 1);
+}
+
+static void rna_Image_active_tile_index_range(
+    PointerRNA *ptr, int *min, int *max, int *UNUSED(softmin), int *UNUSED(softmax))
+{
+  Image *image = (Image *)ptr->data;
+  int num_tiles = BLI_listbase_count(&image->tiles);
+
+  *min = 0;
+  *max = max_ii(0, num_tiles - 1);
+}
+
+static PointerRNA rna_Image_active_tile_get(PointerRNA *ptr)
+{
+  Image *image = (Image *)ptr->data;
+  ImageTile *tile = BLI_findlink(&image->tiles, image->active_tile_index);
+
+  return rna_pointer_inherit_refine(ptr, &RNA_UDIMTile, tile);
+}
+
+static void rna_Image_active_tile_set(PointerRNA *ptr,
+                                      PointerRNA value,
+                                      struct ReportList *UNUSED(reports))
+{
+  Image *image = (Image *)ptr->data;
+  ImageTile *tile = (ImageTile *)value.data;
+  const int index = BLI_findindex(&image->tiles, tile);
+  if (index != -1)
+    image->active_tile_index = index;
+}
+
 static bool rna_Image_has_data_get(PointerRNA *ptr)
 {
   Image *image = (Image *)ptr->data;
@@ -301,7 +384,8 @@ static void rna_Image_resolution_set(PointerRNA *ptr, const float *values)
 static int rna_Image_bindcode_get(PointerRNA *ptr)
 {
   Image *ima = (Image *)ptr->data;
-  GPUTexture *tex = ima->gputexture[TEXTARGET_TEXTURE_2D];
+  ImageTile *tile = BKE_image_get_tile(ima, 0);
+  GPUTexture *tex = tile->gputexture[TEXTARGET_TEXTURE_2D];
   return (tex) ? GPU_texture_opengl_bindcode(tex) : 0;
 }
 
@@ -527,6 +611,23 @@ static void rna_render_slots_active_index_range(
   *max = max_ii(0, BLI_listbase_count(&image->renderslots) - 1);
 }
 
+static ImageTile *rna_UDIMTile_new(Image *image, int tile_number, const char *label)
+{
+  ImageTile *tile = BKE_image_add_tile(image, tile_number, label);
+
+  WM_main_add_notifier(NC_IMAGE | ND_DRAW, NULL);
+
+  return tile;
+}
+
+static void rna_UDIMTile_remove(Image *image, PointerRNA *ptr)
+{
+  ImageTile *tile = (ImageTile *)ptr->data;
+  BKE_image_remove_tile(image, tile);
+
+  WM_main_add_notifier(NC_IMAGE | ND_DRAW, NULL);
+}
+
 #else
 
 static void rna_def_imageuser(BlenderRNA *brna)
@@ -597,6 +698,11 @@ static void rna_def_imageuser(BlenderRNA *brna)
   RNA_def_property_int_sdna(prop, NULL, "view");
   RNA_def_property_clear_flag(prop, PROP_EDITABLE); /* image_multi_cb */
   RNA_def_property_ui_text(prop, "View", "View in multilayer image");
+
+  prop = RNA_def_property(srna, "tile", PROP_INT, PROP_UNSIGNED);
+  RNA_def_property_int_sdna(prop, NULL, "tile");
+  RNA_def_property_clear_flag(prop, PROP_ANIMATABLE);
+  RNA_def_property_ui_text(prop, "Tile", "Tile in tiled image");
 }
 
 /* image.packed_files */
@@ -676,6 +782,79 @@ static void rna_def_render_slots(BlenderRNA *brna, PropertyRNA *cprop)
   RNA_def_function_return(func, parm);
 }
 
+static void rna_def_udim_tile(BlenderRNA *brna)
+{
+  StructRNA *srna;
+  PropertyRNA *prop;
+
+  srna = RNA_def_struct(brna, "UDIMTile", NULL);
+  RNA_def_struct_sdna(srna, "ImageTile");
+  RNA_def_struct_ui_text(srna, "UDIM Tile", "Properties of the UDIM tile");
+
+  prop = RNA_def_property(srna, "label", PROP_STRING, PROP_NONE);
+  RNA_def_property_string_sdna(prop, NULL, "label");
+  RNA_def_property_ui_text(prop, "Label", "Tile label");
+  RNA_def_property_string_funcs(prop, "rna_UDIMTile_label_get", "rna_UDIMTile_label_length", NULL);
+  RNA_def_property_update(prop, NC_IMAGE | ND_DISPLAY, NULL);
+
+  prop = RNA_def_property(srna, "number", PROP_INT, PROP_NONE);
+  RNA_def_property_int_sdna(prop, NULL, "tile_number");
+  RNA_def_property_ui_text(prop, "Number", "Number of the position that this tile covers");
+  RNA_def_property_int_funcs(prop, NULL, "rna_UDIMTile_tile_number_set", NULL);
+  RNA_def_property_update(prop, NC_IMAGE | ND_DISPLAY, NULL);
+}
+
+static void rna_def_udim_tiles(BlenderRNA *brna, PropertyRNA *cprop)
+{
+  StructRNA *srna;
+  PropertyRNA *prop;
+
+  FunctionRNA *func;
+  PropertyRNA *parm;
+
+  RNA_def_property_srna(cprop, "UDIMTiles");
+  srna = RNA_def_struct(brna, "UDIMTiles", NULL);
+  RNA_def_struct_sdna(srna, "Image");
+  RNA_def_struct_ui_text(srna, "UDIM Tiles", "Collection of UDIM tiles");
+
+  prop = RNA_def_property(srna, "active_index", PROP_INT, PROP_UNSIGNED);
+  RNA_def_property_int_sdna(prop, NULL, "active_tile_index");
+  RNA_def_property_int_funcs(prop,
+                             "rna_Image_active_tile_index_get",
+                             "rna_Image_active_tile_index_set",
+                             "rna_Image_active_tile_index_range");
+  RNA_def_property_ui_text(prop, "Active Tile Index", "Active index in tiles array");
+
+  prop = RNA_def_property(srna, "active", PROP_POINTER, PROP_NONE);
+  RNA_def_property_struct_type(prop, "UDIMTile");
+  RNA_def_property_pointer_funcs(
+      prop, "rna_Image_active_tile_get", "rna_Image_active_tile_set", NULL, NULL);
+  RNA_def_property_flag(prop, PROP_EDITABLE | PROP_NEVER_NULL);
+  RNA_def_property_ui_text(prop, "Active Image Tile", "Active Image Tile");
+
+  func = RNA_def_function(srna, "new", "rna_UDIMTile_new");
+  RNA_def_function_ui_description(func, "Add a tile to the image");
+  parm = RNA_def_int(
+      func, "tile_number", 1, 1, INT_MAX, "", "Number of the newly created tile", 1, 100);
+  RNA_def_parameter_flags(parm, 0, PARM_REQUIRED);
+  parm = RNA_def_string(func, "label", NULL, 0, "", "Optional label for the tile");
+  parm = RNA_def_pointer(func, "result", "UDIMTile", "", "Newly created image tile");
+  RNA_def_function_return(func, parm);
+
+  func = RNA_def_function(srna, "get", "BKE_image_get_tile");
+  RNA_def_function_ui_description(func, "Get a tile based on its tile number");
+  parm = RNA_def_int(func, "tile_number", 0, 0, INT_MAX, "", "Number of the tile", 0, 100);
+  RNA_def_parameter_flags(parm, 0, PARM_REQUIRED);
+  parm = RNA_def_pointer(func, "result", "UDIMTile", "", "The tile");
+  RNA_def_function_return(func, parm);
+
+  func = RNA_def_function(srna, "remove", "rna_UDIMTile_remove");
+  RNA_def_function_ui_description(func, "Remove an image tile");
+  parm = RNA_def_pointer(func, "tile", "UDIMTile", "", "Image tile to remove");
+  RNA_def_parameter_flags(parm, PROP_NEVER_NULL, PARM_REQUIRED | PARM_RNAPTR);
+  RNA_def_parameter_clear_flags(parm, PROP_THICK_WRAP, 0);
+}
+
 static void rna_def_image(BlenderRNA *brna)
 {
   StructRNA *srna;
@@ -860,6 +1039,12 @@ static void rna_def_image(BlenderRNA *brna)
   RNA_def_property_ui_text(prop, "Render Slots", "Render slots of the image");
   rna_def_render_slots(brna, prop);
 
+  prop = RNA_def_property(srna, "tiles", PROP_COLLECTION, PROP_NONE);
+  RNA_def_property_struct_type(prop, "UDIMTile");
+  RNA_def_property_collection_sdna(prop, NULL, "tiles", NULL);
+  RNA_def_property_ui_text(prop, "Image Tiles", "Tiles of the image");
+  rna_def_udim_tiles(brna, prop);
+
   /*
    * Image.has_data and Image.depth are temporary,
    * Update import_obj.py when they are replaced (Arystan)
@@ -954,6 +1139,7 @@ static void rna_def_image(BlenderRNA *brna)
 void RNA_def_image(BlenderRNA *brna)
 {
   rna_def_render_slot(brna);
+  rna_def_udim_tile(brna);
   rna_def_image(brna);
   rna_def_imageuser(brna);
   rna_def_image_packed_files(brna);
diff --git a/source/blender/makesrna/intern/rna_image_api.c b/source/blender/makesrna/intern/rna_image_api.c
index 997a5f5ca45..c4ec0a84a2c 100644
--- a/source/blender/makesrna/intern/rna_image_api.c
+++ b/source/blender/makesrna/intern/rna_image_api.c
@@ -174,8 +174,9 @@ static void rna_Image_unpack(Image *image, Main *bmain, ReportList *reports, int
   if (!BKE_image_has_packedfile(image)) {
     BKE_report(reports, RPT_ERROR, "Image not packed");
   }
-  else if (BKE_image_is_animated(image)) {
-    BKE_report(reports, RPT_ERROR, "Unpacking movies or image sequences not supported");
+  else if (BKE_image_has_multiple_ibufs(image)) {
+    BKE_report(
+        reports, RPT_ERROR, "Unpacking movies, image sequences or tiled images not supported");
     return;
   }
   else {
@@ -215,11 +216,12 @@ static void rna_Image_scale(Image *image, ReportList *reports, int width, int he
   }
 }
 
-static int rna_Image_gl_load(Image *image, ReportList *reports, int frame)
+static int rna_Image_gl_load(Image *image, ReportList *reports, int frame, int tile_number)
 {
-  ImageUser iuser = {NULL};
+  ImageUser iuser;
+  BKE_imageuser_default(&iuser);
   iuser.framenr = frame;
-  iuser.ok = true;
+  iuser.tile = tile_number;
 
   GPUTexture *tex = GPU_texture_from_blender(image, &iuser, GL_TEXTURE_2D);
 
@@ -231,14 +233,15 @@ static int rna_Image_gl_load(Image *image, ReportList *reports, int frame)
   return GL_NO_ERROR;
 }
 
-static int rna_Image_gl_touch(Image *image, ReportList *reports, int frame)
+static int rna_Image_gl_touch(Image *image, ReportList *reports, int frame, int tile_number)
 {
   int error = GL_NO_ERROR;
 
   BKE_image_tag_time(image);
 
-  if (image->gputexture[TEXTARGET_TEXTURE_2D] == NULL) {
-    error = rna_Image_gl_load(image, reports, frame);
+  ImageTile *tile = BKE_image_get_tile(image, tile_number);
+  if (tile->gputexture[TEXTARGET_TEXTURE_2D] == NULL) {
+    error = rna_Image_gl_load(image, reports, frame, tile_number);
   }
 
   return error;
@@ -333,6 +336,7 @@ void RNA_api_image(StructRNA *srna)
   RNA_def_function_flag(func, FUNC_USE_REPORTS);
   RNA_def_int(
       func, "frame", 0, 0, INT_MAX, "Frame", "Frame of image sequence or movie", 0, INT_MAX);
+  RNA_def_int(func, "tile_number", 0, 0, INT_MAX, "Tile", "Tile of a tiled image", 0, INT_MAX);
   /* return value */
   parm = RNA_def_int(
       func, "error", 0, -INT_MAX, INT_MAX, "Error", "OpenGL error value", -INT_MAX, INT_MAX);
@@ -347,6 +351,7 @@ void RNA_api_image(StructRNA *srna)
   RNA_def_function_flag(func, FUNC_USE_REPORTS);
   RNA_def_int(
       func, "frame", 0, 0, INT_MAX, "Frame", "Frame of image sequence or movie", 0, INT_MAX);
+  RNA_def_int(func, "tile_number", 0, 0, INT_MAX, "Tile", "Tile of a tiled image", 0, INT_MAX);
   /* return value */
   parm = RNA_def_int(
       func, "error", 0, -INT_MAX, INT_MAX, "Error", "OpenGL error value", -INT_MAX, INT_MAX);
diff --git a/source/blender/makesrna/intern/rna_main_api.c b/source/blender/makesrna/intern/rna_main_api.c
index 2c42dba9131..d85c5c5f249 100644
--- a/source/blender/makesrna/intern/rna_main_api.c
+++ b/source/blender/makesrna/intern/rna_main_api.c
@@ -372,14 +372,24 @@ static Image *rna_Main_images_new(Main *bmain,
                                   bool alpha,
                                   bool float_buffer,
                                   bool stereo3d,
-                                  bool is_data)
+                                  bool is_data,
+                                  bool tiled)
 {
   char safe_name[MAX_ID_NAME - 2];
   rna_idname_validate(name, safe_name);
 
   float color[4] = {0.0, 0.0, 0.0, 1.0};
-  Image *image = BKE_image_add_generated(
-      bmain, width, height, safe_name, alpha ? 32 : 24, float_buffer, 0, color, stereo3d, is_data);
+  Image *image = BKE_image_add_generated(bmain,
+                                         width,
+                                         height,
+                                         safe_name,
+                                         alpha ? 32 : 24,
+                                         float_buffer,
+                                         0,
+                                         color,
+                                         stereo3d,
+                                         is_data,
+                                         tiled);
   id_us_min(&image->id);
   return image;
 }
@@ -1146,6 +1156,7 @@ void RNA_def_main_images(BlenderRNA *brna, PropertyRNA *cprop)
       func, "float_buffer", 0, "Float Buffer", "Create an image with floating point color");
   RNA_def_boolean(func, "stereo3d", 0, "Stereo 3D", "Create left and right views");
   RNA_def_boolean(func, "is_data", 0, "Is Data", "Create image with non-color data color space");
+  RNA_def_boolean(func, "tiled", 0, "Tiled", "Create a tiled image");
   /* return type */
   parm = RNA_def_pointer(func, "image", "Image", "", "New image data-block");
   RNA_def_function_return(func, parm);
diff --git a/source/blender/makesrna/intern/rna_space.c b/source/blender/makesrna/intern/rna_space.c
index 3e6d7352d02..4da6b8214fa 100644
--- a/source/blender/makesrna/intern/rna_space.c
+++ b/source/blender/makesrna/intern/rna_space.c
@@ -1404,7 +1404,7 @@ static const EnumPropertyItem *rna_SpaceImageEditor_display_channels_itemf(
   void *lock;
   int zbuf, alpha, totitem = 0;
 
-  ibuf = ED_space_image_acquire_buffer(sima, &lock);
+  ibuf = ED_space_image_acquire_buffer(sima, &lock, 0);
 
   alpha = ibuf && (ibuf->channels == 4);
   zbuf = ibuf && (ibuf->zbuf || ibuf->zbuf_float || (ibuf->channels == 1));
@@ -1512,7 +1512,8 @@ static void rna_SpaceImageEditor_scopes_update(struct bContext *C, struct Pointe
   ImBuf *ibuf;
   void *lock;
 
-  ibuf = ED_space_image_acquire_buffer(sima, &lock);
+  /* TODO(lukas): Support tiles in scopes? */
+  ibuf = ED_space_image_acquire_buffer(sima, &lock, 0);
   if (ibuf) {
     ED_space_image_scopes_update(C, sima, ibuf, true);
     WM_main_add_notifier(NC_IMAGE, sima->image);
@@ -2803,6 +2804,15 @@ static void rna_def_space_image_uv(BlenderRNA *brna)
   RNA_def_property_ui_text(prop, "Display Faces", "Display faces over the image");
   RNA_def_property_update(prop, NC_SPACE | ND_SPACE_IMAGE, NULL);
 
+  prop = RNA_def_property(srna, "tile_grid_shape", PROP_INT, PROP_NONE);
+  RNA_def_property_int_sdna(prop, NULL, "tile_grid_shape");
+  RNA_def_property_array(prop, 2);
+  RNA_def_property_int_default(prop, 1);
+  RNA_def_property_range(prop, 1, 10);
+  RNA_def_property_ui_text(
+      prop, "Tile Grid Shape", "How many tiles will be shown in the background");
+  RNA_def_property_update(prop, NC_SPACE | ND_SPACE_IMAGE, NULL);
+
   /* todo: move edge and face drawing options here from G.f */
 
   prop = RNA_def_property(srna, "pixel_snap_mode", PROP_ENUM, PROP_NONE);