This topic covers how to write a display driver. Please be aware that writing a Display Driver involves a good understanding of the principles of multi-threaded programming.

What is a Display Driver?

If you're looking to redirect Clarisse render output, for example, to display an image in a custom widget, you'll need to create a Display Driver. A Display Driver is an abstract class that lets you grab the output of the rendering engine in real-time. In Clarisse, the Image View defines a Display Driver and connects it to the image chosen by the user. This is how the Image View in Clarisse is able to display the render progress.

There are no limitations to the number of display drivers connected to an image.

Image evaluation

In Clarisse, images are evaluated by background worker threads. Each image has a predefined set of qualities, acting as multipliers to the image resolution and sampling quality when applicable. To render an image, the evaluation must request a specific quality. Qualities are processed one at the time and they can range from 1/16th of the resolution to full resolution. Please note the complete set of qualities is defined in the ModuleImage::Quality enumeration.

The IOHelpersDisplayDriver class

IOHelpersDisplayDriver is an abstract Display Driver that you must inherit from to retrieve real-time information. There are two categories of methods. The ones that allows you to manage connection and disconnection from a ModuleImage and others that actually receive real-time information from the connected image during its rendering.

When display drivers are connected to an image, they are notified, during rendering, in the following order:

IOHelpersDisplayDriver::on_init_render is called when the rendering starts.
IOHelpersDisplayDriver::on_highlight_region gives the regions that are going to be rendered. It's useful if you wish to display which part of the image are currently being rendered.
IOHelpersDisplayDriver::on_draw_region gives all the regions that have been completed between two calls.
IOHelpersDisplayDriver::on_end_render is called when the rendering ends.
IOHelpersDisplayDriver::on_image_level_update is called when the image of a specific quality is completed.

Depending on the speed of the render, IOHelpersDisplayDriver::on_highlight_region (2) and IOHelpersDisplayDriver::on_draw_region (3) may be called multiple times or even skipped. There are certain cases when the rendering is very quick and only IOHelpersDisplayDriver::on_image_level_update (5) is called skipping IOHelpersDisplayDriver::on_init_render (1). IOHelpersDisplayDriver::on_init_render (1) and IOHelpersDisplayDriver::on_end_render (4) go in pair: if the first one is called, the second one will be also called. The same way if the first one is skipped then the second one is skipped too.

Finally another method IOHelpersDisplayDriver::on_progress_update can be called, once in a while, to retrieve the actual rendering percentage of the current image (from 0.0, not started, to 1.0, completed).

A working example in Python

In this following example, we are going to create a floating window, a push button and a framebuffer display. When the user press the button, the display driver connects to the image currently selected in the application. It then request the image to be evaluated from the lower quality to the full resolution.

There are two classes that are important in this example: DisplayDriver and MyFrameBuffer. The DisplayDriver, here, does all the job and build an image made of buckets. Each rendered buckets are pushed in a list. These buckets are then displayed by MyFrameBuffer.

 #
 # Copyright (C) 2009 - 2020 Isotropix SAS. All rights reserved.
 #
 # The information in this file is provided for the exclusive use of
 # the software licensees of Isotropix. Contents of this file may not
 # be distributed, copied or duplicated in any form, in whole or in
 # part, without the prior written permission of Isotropix SAS.
 #
 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
 import threading
 
 class DisplayDriver(ix.api.IOHelpersDisplayDriver):
     """
     Custom display driver that connects and listens to a Clarisse Image (ModuleImage).
     It inherits from IOHelpersDisplayDriver which is an abstract display driver helper class.
     """
 
     def __init__(self, framebuffer):
         ix.api.IOHelpersDisplayDriver.__init__(self)
         self.framebuffer = framebuffer
         self.buckets = ix.api.GMathVec4iVector()
         self.rendered_regions = ix.api.GMathVec4iVector()
         self.progress_image_w = 0
         self.progress_image_h = 0
 
         # Building the channel list that we need for the display: r, g, b
         self.channels = ix.api.CoreStringVector()
         self.channels.add('r')
         self.channels.add('g')
         self.channels.add('b')
         self.tiles = []
 
     def on_init_render(self, init_data):
         """Called by the rendering thread when it starts to render the image."""
 
         self.framebuffer.lock()
 
         self.buckets.clear()
         self.rendered_regions.clear()
         self.tiles = []
 
         self.framebuffer.image = None
         canvas = init_data.progress_image.get_canvas()
         self.progress_image_w = canvas.get_width()
         self.progress_image_h = canvas.get_height()
 
         self.framebuffer.unlock()
 
         self.framebuffer.must_draw_final_image = False
         self.framebuffer.draw_final_image(init_data.quality, False)
         self.framebuffer.redraw()
 
     def on_end_render(self):
         """Called by the rendering thread when the image is completed."""
 
         self.framebuffer.lock()
         self.buckets.clear()
         self.rendered_regions.clear()
         self.tiles = []
         self.framebuffer.unlock()
 
     def on_highlight_region(self, regions):
         """Called by the rendering thread when starting to render new regions in the image."""
 
         self.framebuffer.lock()
         self.buckets = ix.api.GMathVec4iVector()
         self.buckets.copy_from(regions)
         self.framebuffer.unlock()
         self.framebuffer.redraw()
 
     def on_image_level_update(self, quality, image):
         """Called by the rendering thread when the connected image completes a render quality."""
 
         self.framebuffer.lock()
 
         self.framebuffer.image = None
         self.framebuffer.must_draw_final_image = False
         self.progress_image_w = image.get_canvas().get_width()
         self.progress_image_h = image.get_canvas().get_height()
         self.framebuffer.draw_final_image(quality, True)
         self.buckets.clear()
         self.rendered_regions.clear()
         self.tiles = []
 
         self.framebuffer.unlock()
         self.framebuffer.redraw()
 
     def on_draw_region(self, progress_image, regions):
         """Called by the rendering thread when new regions are available to display."""
 
         self.framebuffer.lock()
 
         # Append the new regions/tiles to our list as we don't want to miss any
         self.rendered_regions.append(regions)
         canvas = progress_image.get_canvas()
         bitmap = ix.api.ImageHelperBitmap()
         for i in range(regions.get_count()):
              r = regions[i]
              # Create a 8-bit bitmap tile from the progress image
              ix.api.ImageHelper.create_bitmap(bitmap, progress_image, r[0], r[1], r[2], r[3], self.channels)
              # Create a GuiImage but you could create a QImage instead
              tile = ix.api.GuiImage(bitmap.get_buffer(), bitmap.get_width(), bitmap.get_height(), self.channels.get_count())
              # Append our new tile to the list to draw it later on
              self.tiles.append(tile)
 
         self.framebuffer.unlock()
         self.framebuffer.redraw()
 
 
 class MyFrameBuffer(ix.api.GuiWidget):
     """
     Widget displaying the image.
     """
 
     def __init__(self, parent, x, y, w, h):
         ix.api.GuiWidget.__init__(self, parent, x, y, w, h)
         self.driver = DisplayDriver(self)
         self.buckets = ix.api.GMathVec4iVector()
         self.buckets_lock = threading.RLock()
         self.must_draw_final_image = False
         self.image = None
 
     def lock(self):
         self.buckets_lock.acquire()
 
     def unlock(self):
         self.buckets_lock.release()
 
     def draw(self, dc):
         if not self.driver.is_connected():
             return
 
         if not self.must_draw_final_image:
             regions = ix.api.GMathVec4iVector()
             rendered_regions = ix.api.GMathVec4iVector()
             dc.draw_rectf(self.get_x(), self.get_y(), self.get_width(), self.get_height(), 0,0,0)
 
             self.lock()
 
             regions = self.driver.buckets
             rendered_regions = self.driver.rendered_regions
 
             # Draw the buckets that are currently being rendered
             if regions.get_count() != 0:
                 for i in range(regions.get_count()):
                     r = regions[i]
                     dc.draw_rect(r[0] + self.get_x(), r[1] + self.get_y(), r[2], r[3], 255, 255, 255)
 
             # Draw all rendered buckets
             tiles = self.driver.tiles
             if rendered_regions.get_count() != 0:
                 i = 0
                 for tile in tiles:
                     r = rendered_regions[i]
                     tile.draw(r[0] + self.get_x(), r[1] + self.get_y())
                     i += 1
             dc.draw_rect(self.get_x(), self.get_y(), self.driver.progress_image_w, self.driver.progress_image_h, 255,0,0)
             self.unlock()
         else:
             dc.draw_rectf(self.get_x(), self.get_y(), self.get_width(), self.get_height(), 0,0,0)
             if self.image != None:
                 self.image.draw(self.get_x(), self.get_y())
                 dc.draw_rect(self.get_x(), self.get_y(), self.image.get_width(), self.image.get_height(), 255, 255, 255)
 
     def draw_final_image(self, quality, flag):
         must_redraw = False
         self.lock()
 
         if flag != self.must_draw_final_image:
             self.must_draw_final_image = flag
             must_redraw = True
             if not flag:
                 # Clear the image
                 self.image = None
             else:
                 bitmap = ix.api.ImageHelperBitmap()
                 module = self.driver.get_image()
                 img = module.get_image(quality)
                 ix.api.ImageHelper.create_bitmap(bitmap, img, 0, 0, img.get_canvas().get_width(), img.get_canvas().get_height(), self.driver.channels)
                 self.image = ix.api.GuiImage(bitmap.get_buffer(), bitmap.get_width(), bitmap.get_height(), self.driver.channels.get_count())
 
         self.unlock()
         if must_redraw:
             self.redraw()
 
 class MyButton(ix.api.GuiPushButton):
     """
     Custom button that connects the display driver to the selected image and requests its render and display.
     """
 
     def __init__(self, parent, x, y, w, h):
         ix.api.GuiPushButton.__init__(self, parent, x, y, w, h, "Connect to Selected Image")
         self.connect(self, 'EVT_ID_PUSH_BUTTON_CLICK', self.on_click)
 
     def on_click(self, sender, evtid):
         if ix.selection.is_empty():
             ix.log_info("Select an Image item.")
             return
 
         item = ix.selection[0]
         if item is not None and item.is_kindof("Image") == False:
             ix.log_info("The selected item is not an Image")
             return
 
         framebuffer = self.get_parent().framebuffer
 
         if framebuffer.driver.is_connected():
             framebuffer.driver.disconnect()
 
         # Clear the FrameBuffer
         framebuffer.lock()
         framebuffer.buckets.clear()
         framebuffer.driver.rendered_regions.clear()
         framebuffer.tiles = []
         framebuffer.unlock()
 
         # Connect the display driver to the selected image
         if framebuffer.driver.connect(item.get_module()) == False:
             ix.log_warning("Failed to connect to Image {}".format(item.get_full_name()))
             return
 
         self.get_parent().set_title("Python Render Window: " + item.get_full_name())
 
         # Request a display of the selected image
         if item.get_module().is_image_dirty(ix.api.ModuleImageQuality.QUALITY_FULL):
             # The image is dirty (not rendered/finished): start the render
             framebuffer.draw_final_image(ix.api.ModuleImageQuality.QUALITY_FULL, False)
             # Launch a progressive evaluation on the image from the lowest quality to full quality.
             # This call is not blocking and exits immediately. It schedules the evaluation of the image
             # in Clarisse's evaluation manager.
             framebuffer.driver.get_image().compute_image(ix.api.ModuleImageQuality.QUALITY_ONE_SIXTEENTH, ix.api.ModuleImageQuality.QUALITY_FULL)
         else:
             # The image is clean (finished), display it
             framebuffer.draw_final_image(ix.api.ModuleImageQuality.QUALITY_FULL, True)
 
 class MyRenderWindow(ix.api.GuiWindow):
     """
     Main window showing the button and the image.
     """
 
     def __init__(self, application, x, y, w, h):
         ix.api.GuiWindow.__init__(self, application, x, y, w, h, "Python Render Window: (none)")
         self.button = MyButton(self, 0, 0, 256, 22)
         self.framebuffer = MyFrameBuffer(self, 0, 22, w, h - 22)
         self.framebuffer.set_constraints(ix.api.GuiWidget.CONSTRAINT_LEFT, ix.api.GuiWidget.CONSTRAINT_TOP, ix.api.GuiWidget.CONSTRAINT_RIGHT, ix.api.GuiWidget.CONSTRAINT_BOTTOM)
 
     def __del__(self):
        # Disconnect the display driver when the window is destroyed.
        self.framebuffer.driver.disconnect()
 
        # Force kill the display driver.
        # Note: there seems there's a destruction bug in Gui when exposed to Python.
        # This isn't necessary if using PyQt.
        self.framebuffer.driver = None
 
 
 # Create the render window
 render_window = MyRenderWindow(ix.application, 0, 0, 640, 480)
 render_window.show()
 
 # Event loop to make the window non-blocking and allow Clarisse to process events
 while render_window.is_shown():
     ix.application.check_for_events(True)

Table of Contents

What is a Display Driver?

Image evaluation

The IOHelpersDisplayDriver class

A working example in Python