api: add ngl_update()

This allows to trigger graph updates without producing frames. This is
particularly useful to trigger a prefetch or release on given graph (without
producing any frame).

libnopegl/src/api.c

@@ -842,6 +842,11 @@ int ngli_prepare_draw(struct ngl_ctx *s, double t)
     return s->api_impl->prepare_draw(s, t);
 }
 
+int ngl_update(struct ngl_ctx *s, double t)
+{
+    return ngli_prepare_draw(s, t);
+}
+
 int ngl_draw(struct ngl_ctx *s, double t)
 {
     if (!s->configured) {

libnopegl/src/nopegl.h.in

@@ -900,6 +900,16 @@ NGL_API int ngl_set_capture_buffer(struct ngl_ctx *s, void *capture_buffer);
  */
 NGL_API int ngl_set_scene(struct ngl_ctx *s, struct ngl_scene *scene);
 
+/**
+ * Update at the specified time.
+ *
+ * @param s     pointer to the configured nope.gl context
+ * @param t     target update time in seconds
+ *
+ * @return 0 on success, NGL_ERROR_* (< 0) on error
+ */
+NGL_API int ngl_update(struct ngl_ctx *s, double t);
+
 /**
  * Draw at the specified time.
  *

pynopegl/_pynopegl.pyx

@@ -184,6 +184,7 @@ cdef extern from "nopegl.h":
     int ngl_get_viewport(ngl_ctx *s, int32_t *viewport)
     int ngl_set_capture_buffer(ngl_ctx *s, void *capture_buffer)
     int ngl_set_scene(ngl_ctx *s, ngl_scene *scene)
+    int ngl_update(ngl_ctx *s, double t) nogil
     int ngl_draw(ngl_ctx *s, double t) nogil
     char *ngl_dot(ngl_ctx *s, double t) nogil
     int ngl_livectls_get(ngl_scene *scene, size_t *nb_livectlsp, ngl_livectl **livectlsp)
@@ -744,6 +745,11 @@ cdef class Context:
             c_scene = <ngl_scene *>ptr
         return ngl_set_scene(self.ctx, c_scene)
 
+    def update(self, double t):
+        with nogil:
+            ret = ngl_update(self.ctx, t)
+        return ret
+
     def draw(self, double t):
         with nogil:
             ret = ngl_draw(self.ctx, t)

tests/api.py

@@ -21,6 +21,7 @@
 
 import atexit
 import csv
+import hashlib
 import locale
 import math
 import os
@@ -677,3 +678,65 @@ def api_transform_chain_check():
         pass
     else:
         assert False
+
+
+def _create_trf_scene_with_media(start, end):
+    mi = load_media("city")
+    media = ngl.Media(mi.filename)
+    texture = ngl.Texture2D(data_src=media)
+    draw = ngl.DrawTexture(texture=texture)
+    group = ngl.Group(children=(draw,))
+    trf = _create_trf(group, start, end)
+
+    return ngl.Scene.from_params(trf)
+
+
+def api_update_with_timeranges(width=320, height=240):
+    """
+    Exercise the `ngl_update()` API
+    """
+    ngl.log_set_min_level(ngl.Log.VERBOSE)
+    capture_buffer = bytearray(width * height * 4)
+    ctx = ngl.Context()
+    ret = ctx.configure(
+        ngl.Config(
+            offscreen=True,
+            width=width,
+            height=height,
+            backend=_backend,
+            capture_buffer=capture_buffer,
+            clear_color=(0.0, 0.0, 0.0, 0.0),
+        )
+    )
+    assert ret == 0
+
+    start = 5.0
+    end = 10.0
+    scene = _create_trf_scene_with_media(start, end)
+    assert ctx.set_scene(scene) == 0
+
+    initial_hash = hashlib.md5(capture_buffer).hexdigest()
+    assert ctx.update(start - 0.5) == 0
+    assert initial_hash == hashlib.md5(capture_buffer).hexdigest()
+
+    assert ctx.draw(start) == 0
+    draw_hash = hashlib.md5(capture_buffer).hexdigest()
+    assert initial_hash != draw_hash
+
+    assert ctx.draw(end - 1.0) == 0
+    assert draw_hash == hashlib.md5(capture_buffer).hexdigest()
+
+    assert ctx.update(end + 1.5) == 0
+    assert draw_hash == hashlib.md5(capture_buffer).hexdigest()
+
+    assert ctx.draw(end + 1.5) == 0
+    assert initial_hash == hashlib.md5(capture_buffer).hexdigest()
+
+    assert ctx.update(end - 1.0) == 0
+    assert initial_hash == hashlib.md5(capture_buffer).hexdigest()
+
+    assert ctx.draw(end - 1.0) == 0
+    assert draw_hash == hashlib.md5(capture_buffer).hexdigest()
+
+    assert ctx.draw(0.0) == 0
+    assert initial_hash == hashlib.md5(capture_buffer).hexdigest()

tests/meson.build

@@ -74,6 +74,7 @@ foreach backend : backends
     'get_backend',
     'viewport',
     'transform_chain_check',
+    'update_with_timeranges',
   ]
   if has_text_libraries
     tests_api += 'text_live_change_with_font'