Class BufferImageStim

source code

Obtain a "screen-shot" (fullscreen, or region) from a buffer, save to a PatchStim()-like RBGA image.

The idea is to be able to speed up the rendering of one or more slow visual elements.
You first make a "collage" image from your static elements, ones that you could treat 
as a being single stim. BufferImageStim optimizes it for speed of rendering in a loop.  
I get ~0.11ms per .draw() on my hardware, regardless of size. But its slow to init:
~75ms for a 1024 x 512 capture, in proportion to image size. There is no support for 
depth, opacity, or color. The idea is to capture
static parts of a display at init() to speed up rendering them.

You specify the part of the screen to capture (in norm units currently), and optionally
the stimuli themselves (as a list of items to be drawn). You
get a screenshot of those pixels. If your OpenGL does not support arbitrary sizes,
the image will be larger, using square powers of two if needed or requested,
with the excess image being invisible (using alpha). The aim is to preserve buffer
contents as rendered, and not "improve" upon them, e.g., through interpolation.
Conceptually, taking a screenshot records whatever has been drawn to the buffer:

Checks for OpenGL 2.1+, or uses square-power-of-2 images.

Status: proof-of-concept. needs real work:
- Screen units are not properly sorted out, good to allow pix as well as norm
- Only rudimentary testing on pygame; none on Windows, Linux, FreeBSD

**Example**::
    # build up a composite or large image (slow, do once):
    mySimpleImageStim.draw()
    myTextStim.draw()
    ...
    # capture everything (one time):
    screenshot = visual.BufferImageStim(myWin)
    ...
    # render to screen (fast, do many times):
    while <conditions>:
        screenshot.draw()  # fast; can change orientation (.ori) or x,y location (._position)
        animation.draw()   # dynamic
        myWin.flip()

See 'bufferImageStim.py' for a demo.

:Author:
    - 2010 Jeremy Gray

:Parameters:
    win :
        A :class:`~psychopy.visual.Window` object (required)
    buffer :
        screen buffer to capture from, default is 'back' (hidden), 'front' (in view after win.flip() )
    rect :
        a list of [left, top, right, bottom] coordinates of a rectangle to capture from the screen.
        currently, these should be given in norm units.
        default is fullscreen: [-1, 1, 1, -1]
    stim :
        if an item or list of items is given, they will be drawn on a cleared back buffer prior to the screenshot,
        and the buffer to be captured will be the back buffer (buffer='front' is ignored).
    interpolate :
        whether to use interpolation (default = True, generally good, especially if you change the orientation)
    sqPower2 :
        False (default) = use rect for size if OpenGL = 2.1+
        True = use square, power-of-two image sizes