docs(IC): convert ImageCache doc example into a compiling test

src/doc/imagecache.rst

@@ -46,46 +46,26 @@ for you.  It is reasonable to access thousands of image files totalling
 hundreds of GB of pixels, efficiently and using a memory footprint on the
 order of 50 MB.
 
-Below are some simple code fragments that shows ImageCache in action::
-
-    #include <OpenImageIO/imagecache.h>
-    using namespace OIIO;
-
-    // Create an image cache and set some options
-    ImageCache *cache = ImageCache::create ();
-    cache->attribute ("max_memory_MB", 500.0f);
-    cache->attribute ("autotile", 64);
-
-    // Get a block of pixels from a file.
-    // (for brevity of this example, let's assume that 'size' is the
-    // number of channels times the number of pixels in the requested region)
-    float pixels[size];
-    cache->get_pixels ("file1.jpg", 0, 0, ROI(xbegin, xend, ybegin, yend),
-                       make_span(pixels));
-
-    // Get information about a file
-    ImageSpec spec;
-    bool ok = cache->get_imagespec ("file2.exr", spec);
-    if (ok)
-        std::cout << "resolution is " << spec.width << "x"
-                  << spec.height << "\n";
-
-    // Request and hold a tile, do some work with its pixels, then release
-    ImageCache::Tile *tile;
-    tile = cache->get_tile ("file2.exr", 0, 0, x, y, z);
-    // The tile won't be freed until we release it, so this is safe:
-    TypeDesc format;
-    void *p = cache->tile_pixels (tile, format);
-    // Now p points to the raw pixels of the tile, whose data format
-    // is given by 'format'.
-    cache->release_tile (tile);
-    // Now cache is permitted to free the tile when needed
-
-    // Note that all files were referenced by name, we never had to open
-    // or close any files, and all the resource and memory management
-    // was automatic.
-
-    ImageCache::destroy (cache);
+Below are some simple code fragments that shows ImageCache in action:
+
+.. tabs::
+
+   .. tab:: C++
+      .. literalinclude:: ../../testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp
+          :language: c++
+          :start-after: BEGIN-imagecache-example1
+          :end-before: END-imagecache-example1
+
+   .. tab:: Python
+
+      .. literalinclude:: ../../testsuite/docs-examples-python/src/docs-examples-imagecache.py
+          :language: py
+          :start-after: BEGIN-imagecache-example1
+          :end-before: END-imagecache-example1
+
+Note that all files were referenced by name, we never had to open
+or close any files, and all the resource and memory management
+was automatic.
 
 
 .. _sec-imagecache-api:

testsuite/docs-examples-cpp/ref/out-arm.txt

@@ -1,4 +1,5 @@
 pixels holds unassociated alpha
+resolution is 512x384
 example_output_error1
 error: Uninitialized input image
 example_output_error2

testsuite/docs-examples-cpp/ref/out-linuxarm.txt

@@ -1,4 +1,5 @@
 pixels holds unassociated alpha
+resolution is 512x384
 example_output_error1
 error: Uninitialized input image
 example_output_error2

testsuite/docs-examples-cpp/ref/out.txt

@@ -1,4 +1,5 @@
 pixels holds unassociated alpha
+resolution is 512x384
 example_output_error1
 error: Uninitialized input image
 example_output_error2

testsuite/docs-examples-cpp/src/docs-examples-imagecache.cpp

@@ -11,20 +11,55 @@
 // "example1" to a helpful short name that identifies the example.
 
 // BEGIN-imagecache-example1
-#include <OpenImageIO/imageio.h>
+#include <OpenImageIO/imagecache.h>
+#include <iostream>
+#include <vector>
 using namespace OIIO;
 
 void
 example1()
 {
-    //
-    // Example code fragment from the docs goes here.
-    //
-    // It probably should generate either some text output (which will show up
-    // in "out.txt" that captures each test's output), or it should produce a
-    // (small) image file that can be compared against a reference image that
-    // goes in the ref/ subdirectory of this test.
-    //
+    // Create an image cache and set some options
+    auto cache = ImageCache::create();
+    cache->attribute("max_memory_MB", 500.0f);
+    cache->attribute("autotile", 64);
+
+    ustring filename("tahoe.tif");
+
+    // Get information about a file
+    ImageSpec spec;
+    bool ok = cache->get_imagespec(filename, spec);
+    if (ok)
+        std::cout << "resolution is " << spec.width << "x" << spec.height
+                   << "\n";
+
+    // Get a block of pixels from a file.
+    const int xbegin = 0, xend = 4, ybegin = 0, yend = 4;
+    const int nchannels = spec.nchannels;
+    ROI roi(xbegin, xend, ybegin, yend, 0, 1, 0, nchannels);
+    std::vector<float> pixels(roi.width() * roi.height() * nchannels);
+    image_span<float> pixelspan(pixels.data(), nchannels, roi.width(),
+                                roi.height());
+    cache->get_pixels(filename, 0, 0, roi, pixelspan);
+
+    // Request and hold a tile, do some work with its pixels, then release
+    ImageCache::Tile* tile = cache->get_tile(filename, 0, 0, 0, 0, 0);
+    if (tile) {
+        // The tile won't be freed until we release it, so this is safe:
+        TypeDesc format;
+        const void* p = cache->tile_pixels(tile, format);
+        // Now p points to the raw pixels of the tile, whose data format
+        // is given by 'format'.
+        (void)p;
+        cache->release_tile(tile);
+        // Now cache is permitted to free the tile when needed
+    }
+
+    // Note that all files were referenced by name, we never had to open
+    // or close any files, and all the resource and memory management
+    // was automatic.
+
+    ImageCache::destroy(cache);
 }
 // END-imagecache-example1
 

testsuite/docs-examples-python/ref/out-arm.txt

@@ -1,4 +1,5 @@
 pixels holds unassociated alpha
+resolution is 512x384
 example1
 example_output_error1
 error: Uninitialized input image

testsuite/docs-examples-python/ref/out-linuxarm.txt

@@ -1,4 +1,5 @@
 pixels holds unassociated alpha
+resolution is 512x384
 example1
 example_output_error1
 error: Uninitialized input image

testsuite/docs-examples-python/ref/out.txt

@@ -1,4 +1,5 @@
 pixels holds unassociated alpha
+resolution is 512x384
 example1
 example_output_error1
 error: Uninitialized input image

testsuite/docs-examples-python/src/docs-examples-imagecache.py

@@ -19,14 +19,24 @@
 import numpy as np
 
 def example1() -> None:
-    #
-    # Example code fragment from the docs goes here.
-    #
-    # It probably should generate either some text output (which will show up
-    # in "out.txt" that captures each test's output), or it should produce a
-    # (small) image file that can be compared against a reference image that
-    # goes in the ref/ subdirectory of this test.
-    #
+    # Create an image cache and set some options
+    cache = oiio.ImageCache()
+    cache.attribute("max_memory_MB", 500.0)
+    cache.attribute("autotile", 64)
+
+    # Get information about a file
+    spec = cache.get_imagespec("tahoe.tif")
+    print(f"resolution is {spec.width}x{spec.height}")
+
+    # Get a block of pixels from a file (returns a numpy array, or None
+    # on failure).
+    roi = oiio.ROI(0, 4, 0, 4, 0, 1, 0, spec.nchannels)
+    pixels = cache.get_pixels("tahoe.tif", 0, 0, roi)
+
+    # Note that all files were referenced by name, we never had to open
+    # or close any files, and all the resource and memory management
+    # was automatic.
+    oiio.ImageCache.destroy(cache)
     return
 
 # END-imagecache-example1