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

1 files changed, 187 insertions, 1 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);