GPU Python: Implement gpu.texture.from_image

It can be useful to replace `image.bindcode` and `image.gl_load`.

Used for example in https://docs.blender.org/api/current/gpu.html#d-image

Reviewed By: brecht

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

4 files changed, 70 insertions, 4 deletions

diff --git a/doc/python_api/sphinx_doc_gen.py b/doc/python_api/sphinx_doc_gen.py
index 2b659de1cf8..5c6cf24a178 100644
--- a/doc/python_api/sphinx_doc_gen.py
+++ b/doc/python_api/sphinx_doc_gen.py
@@ -253,6 +253,7 @@ else:
         "gpu.select",
         "gpu.shader",
         "gpu.state",
+        "gpu.texture",
         "gpu_extras",
         "idprop.types",
         "mathutils",
@@ -1981,10 +1982,11 @@ def write_rst_importable_modules(basepath):
         "imbuf.types": "Image Buffer Types",
         "gpu": "GPU Shader Module",
         "gpu.types": "GPU Types",
-        "gpu.matrix": "GPU Matrix",
-        "gpu.select": "GPU Select",
-        "gpu.shader": "GPU Shader",
-        "gpu.state": "GPU State",
+        "gpu.matrix": "GPU Matrix Utilities",
+        "gpu.select": "GPU Select Utilities",
+        "gpu.shader": "GPU Shader Utilities",
+        "gpu.state": "GPU State Utilities",
+        "gpu.texture": "GPU Texture Utilities",
         "bmesh": "BMesh Module",
         "bmesh.ops": "BMesh Operators",
         "bmesh.types": "BMesh Types",
diff --git a/source/blender/python/gpu/gpu_py_api.c b/source/blender/python/gpu/gpu_py_api.c
index 68f7eb9816c..0bc18e73d0c 100644
--- a/source/blender/python/gpu/gpu_py_api.c
+++ b/source/blender/python/gpu/gpu_py_api.c
@@ -73,6 +73,9 @@ PyObject *BPyInit_gpu(void)
   PyModule_AddObject(mod, "state", (submodule = bpygpu_state_init()));
   PyDict_SetItem(sys_modules, PyModule_GetNameObject(submodule), submodule);
 
+  PyModule_AddObject(mod, "texture", (submodule = bpygpu_texture_init()));
+  PyDict_SetItem(sys_modules, PyModule_GetNameObject(submodule), submodule);
+
   return mod;
 }
 
diff --git a/source/blender/python/gpu/gpu_py_texture.c b/source/blender/python/gpu/gpu_py_texture.c
index 12855b8dbcc..14f901624fe 100644
--- a/source/blender/python/gpu/gpu_py_texture.c
+++ b/source/blender/python/gpu/gpu_py_texture.c
@@ -27,9 +27,13 @@
 
 #include "BLI_string.h"
 
+#include "DNA_image_types.h"
+
 #include "GPU_context.h"
 #include "GPU_texture.h"
 
+#include "BKE_image.h"
+
 #include "../generic/py_capi_utils.h"
 
 #include "gpu_py.h"
@@ -510,6 +514,53 @@ PyTypeObject BPyGPUTexture_Type = {
 /** \} */
 
 /* -------------------------------------------------------------------- */
+/** \name GPU Texture module
+ * \{ */
+PyDoc_STRVAR(pygpu_texture_from_image_doc,
+             ".. function:: from_image(image)\n"
+             "\n"
+             "   Get GPUTexture corresponding to an Image datablock. The GPUTexture memory is "
+             "shared with Blender.\n"
+             "   Note: Colors read from the texture will be in scene linear color space and have "
+             "premultiplied or straight alpha matching the image alpha mode.\n"
+             "\n"
+             "   :arg image: The Image datablock.\n"
+             "   :type image: `bpy.types.Image`\n"
+             "   :return: The GPUTexture used by the image.\n"
+             "   :rtype: :class:`gpu.types.GPUTexture`\n");
+static PyObject *pygpu_texture_from_image(PyObject *UNUSED(self), PyObject *arg)
+{
+  Image *ima = PyC_RNA_AsPointer(arg, "Image");
+  if (ima == NULL) {
+    return NULL;
+  }
+
+  ImageUser iuser;
+  BKE_imageuser_default(&iuser);
+  GPUTexture *tex = BKE_image_get_gpu_texture(ima, &iuser, NULL);
+
+  /* Increase the texture reference count. */
+  GPU_texture_ref(tex);
+
+  return BPyGPUTexture_CreatePyObject(tex);
+}
+
+static struct PyMethodDef pygpu_texture__m_methods[] = {
+    {"from_image", (PyCFunction)pygpu_texture_from_image, METH_O, pygpu_texture_from_image_doc},
+    {NULL, NULL, 0, NULL},
+};
+
+PyDoc_STRVAR(pygpu_texure__m_doc, "This module provides utils for textures.");
+static PyModuleDef pygpu_texture_module_def = {
+    PyModuleDef_HEAD_INIT,
+    .m_name = "gpu.texture",
+    .m_doc = pygpu_texure__m_doc,
+    .m_methods = pygpu_texture__m_methods,
+};
+
+/** \} */
+
+/* -------------------------------------------------------------------- */
 /** \name Local API
  * \{ */
 
@@ -534,6 +585,14 @@ int bpygpu_ParseTexture(PyObject *o, void *p)
   return 1;
 }
 
+PyObject *bpygpu_texture_init(void)
+{
+  PyObject *submodule;
+  submodule = PyModule_Create(&pygpu_texture_module_def);
+
+  return submodule;
+}
+
 /** \} */
 
 /* -------------------------------------------------------------------- */
diff --git a/source/blender/python/gpu/gpu_py_texture.h b/source/blender/python/gpu/gpu_py_texture.h
index be7348b2bd4..5130273f971 100644
--- a/source/blender/python/gpu/gpu_py_texture.h
+++ b/source/blender/python/gpu/gpu_py_texture.h
@@ -31,4 +31,6 @@ typedef struct BPyGPUTexture {
 } BPyGPUTexture;
 
 int bpygpu_ParseTexture(PyObject *o, void *p);
+PyObject *bpygpu_texture_init(void);
+
 PyObject *BPyGPUTexture_CreatePyObject(struct GPUTexture *tex) ATTR_NONNULL(1);