Documentation: Replace the bgl API in the gpu module exemples

doc/python_api/examples/gpu.4.py

@@ -4,7 +4,6 @@ Mesh with Random Vertex Colors
 """
 import bpy
 import gpu
-import bgl
 import numpy as np
 from random import random
 from gpu_extras.batch import batch_for_shader
@@ -31,9 +30,10 @@ batch = batch_for_shader(
 
 
 def draw():
-    bgl.glEnable(bgl.GL_DEPTH_TEST)
+    gpu.state.depth_test_set('LESS_EQUAL')
+    gpu.state.depth_mask_set(True)
     batch.draw(shader)
-    bgl.glDisable(bgl.GL_DEPTH_TEST)
+    gpu.state.depth_mask_set(False)
 
 
 bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_VIEW')

doc/python_api/examples/gpu.6.py

@@ -6,11 +6,11 @@ To use this example you have to provide an image that should be displayed.
 """
 import bpy
 import gpu
-import bgl
 from gpu_extras.batch import batch_for_shader
 
 IMAGE_NAME = "Untitled"
 image = bpy.data.images[IMAGE_NAME]
+texture = gpu.texture.from_image(image)
 
 shader = gpu.shader.from_builtin('2D_IMAGE')
 batch = batch_for_shader(
@@ -21,16 +21,9 @@ batch = batch_for_shader(
     },
 )
 
-if image.gl_load():
-    raise Exception()
-
-
 def draw():
-    bgl.glActiveTexture(bgl.GL_TEXTURE0)
-    bgl.glBindTexture(bgl.GL_TEXTURE_2D, image.bindcode)
-
     shader.bind()
-    shader.uniform_int("image", 0)
+    shader.uniform_sampler("image", texture)
     batch.draw(shader)
 
 

doc/python_api/examples/gpu.7.py

@@ -9,7 +9,6 @@ Generate a texture using Offscreen Rendering
 """
 import bpy
 import gpu
-import bgl
 from mathutils import Matrix
 from gpu_extras.batch import batch_for_shader
 from gpu_extras.presets import draw_circle_2d
@@ -20,8 +19,8 @@ from gpu_extras.presets import draw_circle_2d
 offscreen = gpu.types.GPUOffScreen(512, 512)
 
 with offscreen.bind():
-    bgl.glClearColor(0.0, 0.0, 0.0, 0.0)
-    bgl.glClear(bgl.GL_COLOR_BUFFER_BIT)
+    fb = gpu.state.active_framebuffer_get()
+    fb.clear(color=(0.0, 0.0, 0.0, 0.0))
     with gpu.matrix.push_pop():
         # reset matrices -> use normalized device coordinates [-1, 1]
         gpu.matrix.load_matrix(Matrix.Identity(4))
@@ -75,13 +74,10 @@ batch = batch_for_shader(
 
 
 def draw():
-    bgl.glActiveTexture(bgl.GL_TEXTURE0)
-    bgl.glBindTexture(bgl.GL_TEXTURE_2D, offscreen.color_texture)
-
     shader.bind()
     shader.uniform_float("modelMatrix", Matrix.Translation((1, 2, 3)) @ Matrix.Scale(3, 4))
     shader.uniform_float("viewProjectionMatrix", bpy.context.region_data.perspective_matrix)
-    shader.uniform_float("image", 0)
+    shader.uniform_sampler("image", offscreen.texture_color)
     batch.draw(shader)
 
 

doc/python_api/examples/gpu.8.py

@@ -7,11 +7,10 @@ If it already exists, it will override the existing one.
 
 Currently almost all of the execution time is spent in the last line.
 In the future this will hopefully be solved by implementing the Python buffer protocol
-for :class:`bgl.Buffer` and :class:`bpy.types.Image.pixels` (aka ``bpy_prop_array``).
+for :class:`gpu.types.Buffer` and :class:`bpy.types.Image.pixels` (aka ``bpy_prop_array``).
 """
 import bpy
 import gpu
-import bgl
 import random
 from mathutils import Matrix
 from gpu_extras.presets import draw_circle_2d
@@ -25,8 +24,8 @@ RING_AMOUNT = 10
 offscreen = gpu.types.GPUOffScreen(WIDTH, HEIGHT)
 
 with offscreen.bind():
-    bgl.glClearColor(0.0, 0.0, 0.0, 0.0)
-    bgl.glClear(bgl.GL_COLOR_BUFFER_BIT)
+    fb = gpu.state.active_framebuffer_get()
+    fb.clear(color=(0.0, 0.0, 0.0, 0.0))
     with gpu.matrix.push_pop():
         # reset matrices -> use normalized device coordinates [-1, 1]
         gpu.matrix.load_matrix(Matrix.Identity(4))
@@ -37,9 +36,7 @@ with offscreen.bind():
                 (random.uniform(-1, 1), random.uniform(-1, 1)),
                 (1, 1, 1, 1), random.uniform(0.1, 1), 20)
 
-    buffer = bgl.Buffer(bgl.GL_BYTE, WIDTH * HEIGHT * 4)
-    bgl.glReadBuffer(bgl.GL_BACK)
-    bgl.glReadPixels(0, 0, WIDTH, HEIGHT, bgl.GL_RGBA, bgl.GL_UNSIGNED_BYTE, buffer)
+    buffer = fb.read_color(0, 0, WIDTH, HEIGHT, 4, 0, 'UBYTE')
 
 offscreen.free()
 
@@ -48,4 +45,6 @@ if not IMAGE_NAME in bpy.data.images:
     bpy.data.images.new(IMAGE_NAME, WIDTH, HEIGHT)
 image = bpy.data.images[IMAGE_NAME]
 image.scale(WIDTH, HEIGHT)
+
+buffer.dimensions = WIDTH * HEIGHT * 4
 image.pixels = [v / 255 for v in buffer]

doc/python_api/examples/gpu.9.py

@@ -7,7 +7,6 @@ You could also make this independent of a specific camera,
 but Blender does not expose good functions to create view and projection matrices yet.
 """
 import bpy
-import bgl
 import gpu
 from gpu_extras.presets import draw_texture_2d
 
@@ -34,8 +33,8 @@ def draw():
         view_matrix,
         projection_matrix)
 
-    bgl.glDisable(bgl.GL_DEPTH_TEST)
-    draw_texture_2d(offscreen.color_texture, (10, 10), WIDTH, HEIGHT)
+    gpu.state.depth_mask_set(False)
+    draw_texture_2d(offscreen.texture_color, (10, 10), WIDTH, HEIGHT)
 
 
 bpy.types.SpaceView3D.draw_handler_add(draw, (), 'WINDOW', 'POST_PIXEL')

release/scripts/modules/gpu_extras/presets.py

@@ -57,12 +57,12 @@ def draw_circle_2d(position, color, radius, segments=32):
         batch.draw()
 
 
-def draw_texture_2d(texture_id, position, width, height):
+def draw_texture_2d(texture, position, width, height):
     """
     Draw a 2d texture.
 
-    :arg texture_id: OpenGL id of the texture (e.g. :class:`bpy.types.Image.bindcode`).
-    :type texture_id: int
+    :arg texture: GPUTexture to draw (e.g. gpu.texture.from_image(image) for :class:`bpy.types.Image`).
+    :type texture: :class:`gpu.types.GPUTexture`
     :arg position: Position of the lower left corner.
     :type position: 2D Vector
     :arg width: Width of the image when drawn (not necessarily
@@ -72,7 +72,6 @@ def draw_texture_2d(texture_id, position, width, height):
     :type height: float
     """
     import gpu
-    import bgl
     from . batch import batch_for_shader
 
     coords = ((0, 0), (1, 0), (1, 1), (0, 1))
@@ -83,14 +82,20 @@ def draw_texture_2d(texture_id, position, width, height):
         {"pos": coords, "texCoord": coords},
     )
 
-    bgl.glActiveTexture(bgl.GL_TEXTURE0)
-    bgl.glBindTexture(bgl.GL_TEXTURE_2D, texture_id)
-
     with gpu.matrix.push_pop():
         gpu.matrix.translate(position)
         gpu.matrix.scale((width, height))
 
         shader = gpu.shader.from_builtin('2D_IMAGE')
         shader.bind()
-        shader.uniform_int("image", 0)
+
+        if isinstance(texture, int):
+            # Call the legacy bgl to not break the existing API
+            import bgl
+            bgl.glActiveTexture(bgl.GL_TEXTURE0)
+            bgl.glBindTexture(bgl.GL_TEXTURE_2D, texture)
+            shader.uniform_int("image", 0)
+        else:
+            shader.uniform_sampler("image", texture)
+
         batch.draw(shader)