psychopy 2024.1.0__py3-none-any.whl

psychopy/visual/basevisual.py

@@ -0,0 +1,1952 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+"""Provides class BaseVisualStim and mixins; subclass to get visual stimuli
+"""
+
+# Part of the PsychoPy library
+# Copyright (C) 2002-2018 Jonathan Peirce (C) 2019-2024 Open Science Tools Ltd.
+# Distributed under the terms of the GNU General Public License (GPL).
+
+from pathlib import Path
+from statistics import mean
+from psychopy.colors import Color, colorSpaces
+from psychopy.layout import Vector, Position, Size, Vertices, unitTypes
+
+# Ensure setting pyglet.options['debug_gl'] to False is done prior to any
+# other calls to pyglet or pyglet submodules, otherwise it may not get picked
+# up by the pyglet GL engine and have no effect.
+# Shaders will work but require OpenGL2.0 drivers AND PyOpenGL3.0+
+
+import pyglet
+pyglet.options['debug_gl'] = False
+GL = pyglet.gl
+
+try:
+    from PIL import Image
+except ImportError:
+    from . import Image
+
+import copy
+import sys
+import os
+import ctypes
+from psychopy import logging
+
+# tools must only be imported *after* event or MovieStim breaks on win32
+# (JWP has no idea why!)
+from psychopy.tools.arraytools import val2array
+from psychopy.tools.attributetools import (attributeSetter, logAttrib,
+                                           setAttribute, AttributeGetSetMixin)
+from psychopy.tools.monitorunittools import (cm2pix, deg2pix, pix2cm,
+                                             pix2deg, convertToPix)
+from psychopy.visual.helpers import (pointInPolygon, polygonsOverlap,
+                                     setColor, findImageFile)
+from psychopy.tools.typetools import float_uint8
+from psychopy.tools.arraytools import makeRadialMatrix, createLumPattern
+from psychopy.event import Mouse
+from psychopy.tools.colorspacetools import dkl2rgb, lms2rgb  # pylint: disable=W0611
+
+from . import globalVars
+
+import numpy
+from numpy import pi
+
+from psychopy.constants import NOT_STARTED, STARTED, STOPPED
+
+reportNImageResizes = 5  # permitted number of resizes
+
+"""
+There are several base and mix-in visual classes for multiple inheritance:
+  - MinimalStim:       non-visual house-keeping code common to all visual stim
+        RatingScale inherits only from MinimalStim.
+  - WindowMixin:       attributes/methods about the stim relative to
+        a visual.Window.
+  - LegacyVisualMixin: deprecated visual methods (eg, setRGB) added
+        to BaseVisualStim
+  - ColorMixin:        for Stim that need color methods (most, not Movie)
+        color-related methods and attribs
+  - ContainerMixin:    for stim that need polygon .contains() methods.
+        Most need this, but not Text. .contains(), .overlaps()
+  - TextureMixin:      for texture methods namely _createTexture
+        (Grating, not Text)
+        seems to work; caveat: There were issues in earlier (non-MI) versions
+        of using _createTexture so it was pulled out of classes.
+        Now it's inside classes again. Should be watched.
+  - BaseVisualStim:    = Minimal + Window + Legacy. Furthermore adds c
+        ommon attributes like orientation, opacity, contrast etc.
+
+Typically subclass BaseVisualStim to create new visual stim classes, and add
+mixin(s) as needed to add functionality.
+"""
+
+
+class MinimalStim(AttributeGetSetMixin):
+    """Non-visual methods and attributes for BaseVisualStim and RatingScale.
+
+    Includes: name, autoDraw, autoLog, status, __str__
+    """
+
+    def __init__(self, name=None, autoLog=None):
+        if name not in (None, ''):
+            self.__dict__['name'] = name
+        else:
+            self.__dict__['name'] = 'unnamed %s' % self.__class__.__name__
+        self.status = NOT_STARTED
+        self.autoLog = autoLog
+        self.validator = None
+        super(MinimalStim, self).__init__()
+        if self.autoLog:
+            msg = ("%s is calling MinimalStim.__init__() with autolog=True. "
+                   "Set autoLog to True only at the end of __init__())")
+            logging.warning(msg % self.__class__.__name__)
+
+    def __str__(self, complete=False):
+        """
+        """
+        if hasattr(self, '_initParams'):
+            className = self.__class__.__name__
+            paramStrings = []
+            for param in self._initParams:
+                if hasattr(self, param):
+                    val = getattr(self, param)
+                    valStr = repr(getattr(self, param))
+                    if len(repr(valStr)) > 50 and not complete:
+                        if val.__class__.__name__ == 'attributeSetter':
+                            _name = val.__getattribute__.__class__.__name__
+                        else:
+                            _name = val.__class__.__name__
+                        valStr = "%s(...)" % _name
+                else:
+                    valStr = 'UNKNOWN'
+                paramStrings.append("%s=%s" % (param, valStr))
+            # this could be used if all params are known to exist:
+            # paramStrings = ["%s=%s" %(param, getattr(self, param))
+            #     for param in self._initParams]
+            params = ", ".join(paramStrings)
+            s = "%s(%s)" % (className, params)
+        else:
+            s = object.__repr__(self)
+        return s
+
+    # Might seem simple at first, but this ensures that "name" attribute
+    # appears in docs and that name setting and updating is logged.
+    @attributeSetter
+    def name(self, value):
+        """The name (`str`) of the object to be using during logged messages
+        about this stim. If you have multiple stimuli in your experiment this
+        really helps to make sense of log files!
+
+        If name = None your stimulus will be called "unnamed <type>", e.g.
+        visual.TextStim(win) will be called "unnamed TextStim" in the logs.
+        """
+        self.__dict__['name'] = value
+
+    @attributeSetter
+    def autoDraw(self, value):
+        """Determines whether the stimulus should be automatically drawn
+        on every frame flip.
+
+        Value should be: `True` or `False`. You do NOT need to set this
+        on every frame flip!
+        """
+        self.__dict__['autoDraw'] = value
+        toDraw = self.win._toDraw
+        toDrawDepths = self.win._toDrawDepths
+        beingDrawn = (self in toDraw)
+        if value == beingDrawn:
+            return  # nothing to do
+        elif value:
+            # work out where to insert the object in the autodraw list
+            depthArray = numpy.array(toDrawDepths)
+            # all indices where true:
+            iis = numpy.where(depthArray < self.depth)[0]
+            if len(iis):  # we featured somewhere before the end of the list
+                toDraw.insert(iis[0], self)
+                toDrawDepths.insert(iis[0], self.depth)
+            else:
+                toDraw.append(self)
+                toDrawDepths.append(self.depth)
+            # Add to editable list (if needed)
+            self.win.addEditable(self)
+            # Mark as started
+            self.status = STARTED
+        elif value == False:
+            # remove from autodraw lists
+            toDrawDepths.pop(toDraw.index(self))  # remove from depths
+            toDraw.remove(self)  # remove from draw list
+            # Remove from editable list (if needed)
+            self.win.removeEditable(self)
+            # Mark as stopped
+            self.status = STOPPED
+
+    def setAutoDraw(self, value, log=None):
+        """Sets autoDraw. Usually you can use 'stim.attribute = value'
+        syntax instead, but use this method to suppress the log message.
+        """
+        setAttribute(self, 'autoDraw', value, log)
+
+    @attributeSetter
+    def autoLog(self, value):
+        """Whether every change in this stimulus should be auto logged.
+
+        Value should be: `True` or `False`. Set to `False` if your stimulus is
+        updating frequently (e.g. updating its position every frame) and you
+        want to avoid swamping the log file with messages that aren't likely to
+        be useful.
+        """
+        self.__dict__['autoLog'] = value
+
+    def setAutoLog(self, value=True, log=None):
+        """Usually you can use 'stim.attribute = value' syntax instead,
+        but use this method if you need to suppress the log message.
+        """
+        setAttribute(self, 'autoLog', value, log)
+
+
+class LegacyVisualMixin:
+    """Class to hold deprecated visual methods and attributes.
+
+    Intended only for use as a mixin class for BaseVisualStim, to maintain
+    backwards compatibility while reducing clutter in class BaseVisualStim.
+    """
+    # def __init__(self):
+    #    super(LegacyVisualMixin, self).__init__()
+
+    def _calcSizeRendered(self):
+        """DEPRECATED in 1.80.00. This functionality is now handled
+        by _updateVertices() and verticesPix
+        """
+        # raise DeprecationWarning, "_calcSizeRendered() was deprecated in
+        # 1.80.00. This functionality is now handled by _updateVertices()
+        # and verticesPix"
+        if self.units in ['norm', 'pix', 'height']:
+            self._sizeRendered = copy.copy(self.size)
+        elif self.units in ['deg', 'degs']:
+            self._sizeRendered = deg2pix(self.size, self.win.monitor)
+        elif self.units == 'cm':
+            self._sizeRendered = cm2pix(self.size, self.win.monitor)
+        else:
+            logging.error("Stimulus units should be 'height', 'norm', "
+                          "'deg', 'cm' or 'pix', not '%s'" % self.units)
+
+    def _calcPosRendered(self):
+        """DEPRECATED in 1.80.00. This functionality is now handled
+        by _updateVertices() and verticesPix.
+        """
+        # raise DeprecationWarning, "_calcSizeRendered() was deprecated
+        #  in 1.80.00. This functionality is now handled by
+        # _updateVertices() and verticesPix"
+        if self.units in ['norm', 'pix', 'height']:
+            self._posRendered = copy.copy(self.pos)
+        elif self.units in ['deg', 'degs']:
+            self._posRendered = deg2pix(self.pos, self.win.monitor)
+        elif self.units == 'cm':
+            self._posRendered = cm2pix(self.pos, self.win.monitor)
+
+    def _getPolyAsRendered(self):
+        """DEPRECATED. Return a list of vertices as rendered.
+        """
+        oriRadians = numpy.radians(self.ori)
+        sinOri = numpy.sin(-oriRadians)
+        cosOri = numpy.cos(-oriRadians)
+        x = (self._verticesRendered[:, 0] * cosOri -
+             self._verticesRendered[:, 1] * sinOri)
+        y = (self._verticesRendered[:, 0] * sinOri +
+             self._verticesRendered[:, 1] * cosOri)
+        return numpy.column_stack((x, y)) + self._posRendered
+
+    @attributeSetter
+    def depth(self, value):
+        """DEPRECATED, depth is now controlled simply by drawing order.
+        """
+        self.__dict__['depth'] = value
+
+
+class LegacyForeColorMixin:
+    """
+    Mixin class to give an object all of the legacy functions for setting foreground color
+    """
+    def setDKL(self, color, operation=''):
+        """DEPRECATED since v1.60.05: Please use the `color` attribute
+        """
+        self.setForeColor(color, 'dkl', operation)
+
+    def setLMS(self, color, operation=''):
+        """DEPRECATED since v1.60.05: Please use the `color` attribute
+        """
+        self.setForeColor(color, 'lms', operation)
+
+    @property
+    def foreRGB(self):
+        """
+        DEPRECATED: Legacy property for setting the foreground color of a stimulus in RGB, instead use `obj._foreColor.rgb`
+        """
+        return self._foreColor.rgb
+
+    @foreRGB.setter
+    def foreRGB(self, value):
+        self.foreColor = Color(value, 'rgb')
+
+    @property
+    def RGB(self):
+        """
+        DEPRECATED: Legacy property for setting the foreground color of a stimulus in RGB, instead use `obj._foreColor.rgb`
+        """
+        return self.foreRGB
+
+    @RGB.setter
+    def RGB(self, value):
+        self.foreRGB = value
+
+    def setRGB(self, color, operation='', log=None):
+        """
+        DEPRECATED: Legacy setter for foreground RGB, instead set `obj._foreColor.rgb`
+        """
+        self.setForeColor(color, 'rgb', operation, log)
+
+    def setForeRGB(self, color, operation='', log=None):
+        """
+        DEPRECATED: Legacy setter for foreground RGB, instead set `obj._foreColor.rgb`
+        """
+        self.setForeColor(color, 'rgb', operation, log)
+
+    @property
+    def foreColorSpace(self):
+        """Deprecated, please use colorSpace to set color space for the entire
+        object.
+        """
+        return self.colorSpace
+
+    @foreColorSpace.setter
+    def foreColorSpace(self, value):
+        logging.warning(
+            "Setting color space by attribute rather than by object is deprecated. Value of foreColorSpace has been assigned to colorSpace.")
+        self.colorSpace = value
+
+
+class LegacyFillColorMixin:
+    """
+    Mixin class to give an object all of the legacy functions for setting fill color
+    """
+    @property
+    def fillRGB(self):
+        """
+        DEPRECATED: Legacy property for setting the fill color of a stimulus in RGB, instead use `obj._fillColor.rgb`
+        """
+        return self._fillColor.rgb
+
+    @fillRGB.setter
+    def fillRGB(self, value):
+        self.fillColor = Color(value, 'rgb')
+
+    @property
+    def backRGB(self):
+        """
+        DEPRECATED: Legacy property for setting the fill color of a stimulus in RGB, instead use `obj._fillColor.rgb`
+        """
+        return self.fillRGB
+
+    @backRGB.setter
+    def backRGB(self, value):
+        self.fillRGB = value
+
+    def setFillRGB(self, color, operation='', log=None):
+        """
+        DEPRECATED: Legacy setter for fill RGB, instead set `obj._fillColor.rgb`
+        """
+        self.setFillColor(color, 'rgb', operation, log)
+
+    def setBackRGB(self, color, operation='', log=None):
+        """
+        DEPRECATED: Legacy setter for fill RGB, instead set `obj._fillColor.rgb`
+        """
+        self.setFillColor(color, 'rgb', operation, log)
+
+    @property
+    def fillColorSpace(self):
+        """Deprecated, please use colorSpace to set color space for the entire
+        object.
+        """
+        return self.colorSpace
+
+    @fillColorSpace.setter
+    def fillColorSpace(self, value):
+        logging.warning("Setting color space by attribute rather than by object is deprecated. Value of fillColorSpace has been assigned to colorSpace.")
+        self.colorSpace = value
+
+    @property
+    def backColorSpace(self):
+        """Deprecated, please use colorSpace to set color space for the entire
+        object.
+        """
+        return self.colorSpace
+
+    @backColorSpace.setter
+    def backColorSpace(self, value):
+        logging.warning(
+            "Setting color space by attribute rather than by object is deprecated. Value of backColorSpace has been assigned to colorSpace.")
+        self.colorSpace = value
+
+
+class LegacyBorderColorMixin:
+    """
+    Mixin class to give an object all of the legacy functions for setting border color
+    """
+    @property
+    def borderRGB(self):
+        """
+        DEPRECATED: Legacy property for setting the border color of a stimulus in RGB, instead use `obj._borderColor.rgb`
+        """
+        return self._borderColor.rgb
+
+    @borderRGB.setter
+    def borderRGB(self, value):
+        self.borderColor = Color(value, 'rgb')
+
+    @property
+    def lineRGB(self):
+        """
+        DEPRECATED: Legacy property for setting the border color of a stimulus in RGB, instead use `obj._borderColor.rgb`
+        """
+        return self.borderRGB
+
+    @lineRGB.setter
+    def lineRGB(self, value):
+        self.borderRGB = value
+
+    def setBorderRGB(self, color, operation='', log=None):
+        """
+        DEPRECATED: Legacy setter for border RGB, instead set `obj._borderColor.rgb`
+        """
+        self.setBorderColor(color, 'rgb', operation, log)
+
+    def setLineRGB(self, color, operation='', log=None):
+        """
+        DEPRECATED: Legacy setter for border RGB, instead set `obj._borderColor.rgb`
+        """
+        self.setBorderColor(color, 'rgb', operation, log)
+
+    @property
+    def borderColorSpace(self):
+        """Deprecated, please use colorSpace to set color space for the entire
+        object
+        """
+        return self.colorSpace
+
+    @borderColorSpace.setter
+    def borderColorSpace(self, value):
+        logging.warning(
+            "Setting color space by attribute rather than by object is deprecated. Value of borderColorSpace has been assigned to colorSpace.")
+        self.colorSpace = value
+
+    @property
+    def lineColorSpace(self):
+        """Deprecated, please use colorSpace to set color space for the entire
+        object
+        """
+        return self.colorSpace
+
+    @lineColorSpace.setter
+    def lineColorSpace(self, value):
+        logging.warning(
+            "Setting color space by attribute rather than by object is deprecated. Value of lineColorSpace has been assigned to colorSpace.")
+        self.colorSpace = value
+
+
+class LegacyColorMixin(LegacyForeColorMixin, LegacyFillColorMixin, LegacyBorderColorMixin):
+    """
+    Mixin class to give an object all of the legacy functions for setting all colors (fore, fill and border
+    """
+
+
+class BaseColorMixin:
+    """
+    Mixin class giving base color methods (e.g. colorSpace) which are needed for any color stuff.
+    """
+    @property
+    def colorSpace(self):
+        """The name of the color space currently being used
+
+        Value should be: a string or None
+
+        For strings and hex values this is not needed.
+        If None the default colorSpace for the stimulus is
+        used (defined during initialisation).
+
+        Please note that changing colorSpace does not change stimulus
+        parameters. Thus you usually want to specify colorSpace before
+        setting the color. Example::
+
+            # A light green text
+            stim = visual.TextStim(win, 'Color me!',
+                                   color=(0, 1, 0), colorSpace='rgb')
+
+            # An almost-black text
+            stim.colorSpace = 'rgb255'
+
+            # Make it light green again
+            stim.color = (128, 255, 128)
+        """
+        if hasattr(self, '_colorSpace'):
+            return self._colorSpace
+        else:
+            return 'rgba'
+
+    @colorSpace.setter
+    def colorSpace(self, value):
+        if value in colorSpaces:
+            self._colorSpace = value
+        else:
+            logging.error(f"'{value}' is not a valid color space")
+
+    @property
+    def contrast(self):
+        """A value that is simply multiplied by the color.
+
+        Value should be: a float between -1 (negative) and 1 (unchanged).
+            :ref:`Operations <attrib-operations>` supported.
+
+        Set the contrast of the stimulus, i.e. scales how far the stimulus
+        deviates from the middle grey. You can also use the stimulus
+        `opacity` to control contrast, but that cannot be negative.
+
+        Examples::
+
+            stim.contrast =  1.0  # unchanged contrast
+            stim.contrast =  0.5  # decrease contrast
+            stim.contrast =  0.0  # uniform, no contrast
+            stim.contrast = -0.5  # slightly inverted
+            stim.contrast = -1.0  # totally inverted
+
+        Setting contrast outside range -1 to 1 is permitted, but may
+        produce strange results if color values exceeds the monitor limits.::
+
+            stim.contrast =  1.2  # increases contrast
+            stim.contrast = -1.2  # inverts with increased contrast
+
+        """
+        if hasattr(self, '_foreColor'):
+            return self._foreColor.contrast
+
+    @contrast.setter
+    def contrast(self, value):
+        if hasattr(self, '_foreColor'):
+            self._foreColor.contrast = value
+        if hasattr(self, '_fillColor'):
+            self._fillColor.contrast = value
+        if hasattr(self, '_borderColor'):
+            self._borderColor.contrast = value
+
+    def setContrast(self, newContrast, operation='', log=None):
+        """Usually you can use 'stim.attribute = value' syntax instead,
+        but use this method if you need to suppress the log message
+        """
+        if newContrast is not None:
+            self.contrast = newContrast
+        if operation in ['', '=']:
+            self.contrast = newContrast
+        elif operation in ['+']:
+            self.contrast += newContrast
+        elif operation in ['-']:
+            self.contrast -= newContrast
+        else:
+            logging.error(f"Operation '{operation}' not recognised.")
+
+    def _getDesiredRGB(self, rgb, colorSpace, contrast):
+        """ Convert color to RGB while adding contrast.
+        Requires self.rgb, self.colorSpace and self.contrast
+        """
+        col = Color(rgb, colorSpace)
+        col.contrast *= contrast or 0
+        return col.render('rgb')
+
+    def updateColors(self):
+        """Placeholder method to update colours when set externally, for example updating the `pallette` attribute of
+        a textbox"""
+        return
+
+
+class ForeColorMixin(BaseColorMixin, LegacyForeColorMixin):
+    """
+    Mixin class for visual stim that need fore color.
+    """
+    @property
+    def foreColor(self):
+        """Foreground color of the stimulus
+
+        Value should be one of:
+            + string: to specify a :ref:`colorNames`. Any of the standard
+              html/X11 `color names
+              <http://www.w3schools.com/html/html_colornames.asp>`
+              can be used.
+            + :ref:`hexColors`
+            + numerically: (scalar or triplet) for DKL, RGB or
+                other :ref:`colorspaces`. For
+                these, :ref:`operations <attrib-operations>` are supported.
+
+        When color is specified using numbers, it is interpreted with
+        respect to the stimulus' current colorSpace. If color is given as a
+        single value (scalar) then this will be applied to all 3 channels.
+
+        Examples
+        --------
+        For whatever stim you have::
+
+            stim.color = 'white'
+            stim.color = 'RoyalBlue'  # (the case is actually ignored)
+            stim.color = '#DDA0DD'  # DDA0DD is hexadecimal for plum
+            stim.color = [1.0, -1.0, -1.0]  # if stim.colorSpace='rgb':
+                            # a red color in rgb space
+            stim.color = [0.0, 45.0, 1.0]  # if stim.colorSpace='dkl':
+                            # DKL space with elev=0, azimuth=45
+            stim.color = [0, 0, 255]  # if stim.colorSpace='rgb255':
+                            # a blue stimulus using rgb255 space
+            stim.color = 255  # interpreted as (255, 255, 255)
+                              # which is white in rgb255.
+
+
+        :ref:`Operations <attrib-operations>` work as normal for all numeric
+        colorSpaces (e.g. 'rgb', 'hsv' and 'rgb255') but not for strings, like
+        named and hex. For example, assuming that colorSpace='rgb'::
+
+            stim.color += [1, 1, 1]  # increment all guns by 1 value
+            stim.color *= -1  # multiply the color by -1 (which in this
+                                # space inverts the contrast)
+            stim.color *= [0.5, 0, 1]  # decrease red, remove green, keep blue
+
+        You can use `setColor` if you want to set color and colorSpace in one
+        line. These two are equivalent::
+
+            stim.setColor((0, 128, 255), 'rgb255')
+            # ... is equivalent to
+            stim.colorSpace = 'rgb255'
+            stim.color = (0, 128, 255)
+        """
+        if hasattr(self, '_foreColor'):
+            return self._foreColor.render(self.colorSpace)
+
+    @foreColor.setter
+    def foreColor(self, value):
+        if isinstance(value, Color):
+            # If supplied with a Color object, set as that
+            self._foreColor = value
+        else:
+            # Otherwise, make a new Color object
+            self._foreColor = Color(value, self.colorSpace, contrast=self.contrast)
+        if not self._foreColor:
+            self._foreColor = Color()
+            logging.error(f"'{value}' is not a valid {self.colorSpace} color")
+        # Handle logging
+        logAttrib(self, log=None, attrib="foreColor", value=value)
+
+    @property
+    def color(self):
+        """Alternative way of setting `foreColor`."""
+        return self.foreColor
+
+    @color.setter
+    def color(self, value):
+        self.foreColor = value
+
+    @property
+    def fontColor(self):
+        """Alternative way of setting `foreColor`."""
+        return self.foreColor
+
+    @fontColor.setter
+    def fontColor(self, value):
+        self.foreColor = value
+
+    def setForeColor(self, color, colorSpace=None, operation='', log=None):
+        """Hard setter for foreColor, allows suppression of the log message,
+        simultaneous colorSpace setting and calls update methods.
+        """
+        setColor(obj=self, colorAttrib="foreColor", color=color, colorSpace=colorSpace or self.colorSpace, operation=operation, log=log)
+        # Trigger color update for components like Textbox which have different behaviours for a hard setter
+        self.updateColors()
+
+    def setColor(self, color, colorSpace=None, operation='', log=None):
+        self.setForeColor(color, colorSpace=colorSpace, operation=operation, log=log)
+
+    def setFontColor(self, color, colorSpace=None, operation='', log=None):
+        self.setForeColor(color, colorSpace=colorSpace, operation=operation, log=log)
+
+
+class FillColorMixin(BaseColorMixin, LegacyFillColorMixin):
+    """
+    Mixin class for visual stim that need fill color.
+    """
+
+    @property
+    def fillColor(self):
+        """Set the fill color for the shape."""
+        if hasattr(self, '_fillColor'):
+            return getattr(self._fillColor, self.colorSpace)  # return self._fillColor.render(self.colorSpace)
+
+    @fillColor.setter
+    def fillColor(self, value):
+        if isinstance(value, Color):
+            # If supplied with a color object, set as that
+            self._fillColor = value
+        else:
+            # Otherwise, make a new Color object
+            self._fillColor = Color(value, self.colorSpace, contrast=self.contrast)
+        if not self._fillColor:
+            # If given an invalid color, set as transparent and log error
+            self._fillColor = Color()
+            logging.error(f"'{value}' is not a valid {self.colorSpace} color")
+        # Handle logging
+        logAttrib(self, log=None, attrib="fillColor", value=value)
+
+    @property
+    def backColor(self):
+        """Alternative way of setting fillColor"""
+        return self.fillColor
+
+    @backColor.setter
+    def backColor(self, value):
+        self.fillColor = value
+
+    @property
+    def backgroundColor(self):
+        """Alternative way of setting fillColor"""
+        return self.fillColor
+
+    @backgroundColor.setter
+    def backgroundColor(self, value):
+        self.fillColor = value
+
+    def setFillColor(self, color, colorSpace=None, operation='', log=None):
+        """Hard setter for fillColor, allows suppression of the log message,
+        simultaneous colorSpace setting and calls update methods.
+        """
+        setColor(obj=self, colorAttrib="fillColor", color=color, colorSpace=colorSpace or self.colorSpace, operation=operation, log=log)
+        # Trigger color update for components like Textbox which have different behaviours for a hard setter
+        self.updateColors()
+
+    def setBackColor(self, color, colorSpace=None, operation='', log=None):
+        self.setFillColor(color, colorSpace=colorSpace, operation=operation, log=log)
+
+    def setBackgroundColor(self, color, colorSpace=None, operation='', log=None):
+        self.setFillColor(color, colorSpace=colorSpace, operation=operation, log=log)
+
+
+class BorderColorMixin(BaseColorMixin, LegacyBorderColorMixin):
+    @property
+    def borderColor(self):
+        if hasattr(self, '_borderColor'):
+            return self._borderColor.render(self.colorSpace)
+
+    @borderColor.setter
+    def borderColor(self, value):
+        if isinstance(value, Color):
+            # If supplied with a color object, set as that
+            self._borderColor = value
+        else:
+            # If supplied with a valid color, use it to make a color object
+            self._borderColor = Color(value, self.colorSpace, contrast=self.contrast)
+        if not self._borderColor:
+            # If given an invalid color, set as transparent and log error
+            self._borderColor = Color()
+            logging.error(f"'{value}' is not a valid {self.colorSpace} color")
+
+        # Handle logging
+        logAttrib(self, log=None, attrib="borderColor", value=value)
+
+    @property
+    def lineColor(self):
+        """Alternative way of setting `borderColor`."""
+        return self.borderColor
+
+    @lineColor.setter
+    def lineColor(self, value):
+        self.borderColor = value
+
+    def setBorderColor(self, color, colorSpace=None, operation='', log=None):
+        """Hard setter for `fillColor`, allows suppression of the log message,
+        simultaneous colorSpace setting and calls update methods.
+        """
+        setColor(obj=self, colorAttrib="borderColor", color=color, colorSpace=colorSpace or self.colorSpace, operation=operation, log=log)
+        # Trigger color update for components like Textbox which have different behaviours for a hard setter
+        self.updateColors()
+
+    def setLineColor(self, color, colorSpace=None, operation='', log=None):
+        self.setBorderColor(color, colorSpace=None, operation='', log=None)
+
+    @attributeSetter
+    def borderWidth(self, value):
+        self.__dict__['borderWidth'] = value
+        return self.__dict__['borderWidth']
+
+    def setBorderWidth(self, newWidth, operation='', log=None):
+        setAttribute(self, 'borderWidth', newWidth, log, operation)
+
+    @attributeSetter
+    def lineWidth(self, value):
+        self.__dict__['borderWidth'] = value
+        return self.__dict__['borderWidth']
+
+    def setLineWidth(self, newWidth, operation='', log=None):
+        setAttribute(self, 'lineWidth', newWidth, log, operation)
+
+
+class ColorMixin(ForeColorMixin, FillColorMixin, BorderColorMixin):
+    """
+    Mixin class for visual stim that need fill, fore and border color.
+    """
+
+
+class ContainerMixin:
+    """Mixin class for visual stim that have verticesPix attrib
+    and .contains() methods.
+    """
+
+    def __init__(self):
+        super(ContainerMixin, self).__init__()
+        self._verticesBase = numpy.array(
+            [[0.5, -0.5], [-0.5, -0.5], [-0.5, 0.5], [0.5, 0.5]])  # sqr
+        self._borderBase = numpy.array(
+            [[0.5, -0.5], [-0.5, -0.5], [-0.5, 0.5], [0.5, 0.5]])  # sqr
+        self._rotationMatrix = [[1., 0.], [0., 1.]]  # no rotation by default
+
+    @property
+    def verticesPix(self):
+        """This determines the coordinates of the vertices for the
+        current stimulus in pixels, accounting for size, ori, pos and units
+        """
+        # because this is a property getter we can check /on-access/ if it
+        # needs updating :-)
+        if self._needVertexUpdate:
+            self._updateVertices()
+        return self.__dict__['verticesPix']
+
+    @property
+    def _borderPix(self):
+        """Allows for a dynamic border that differs from self.vertices, gets
+        updated dynamically with identical transformations.
+        """
+        if not hasattr(self, 'border'):
+            msg = "%s._borderPix requested without .border" % self.name
+            logging.error(msg)
+            raise AttributeError(msg)
+        if self._needVertexUpdate:
+            self._updateVertices()
+        return self.__dict__['_borderPix']
+
+    def _updateVertices(self):
+        """Sets Stim.verticesPix and ._borderPix from pos, size, ori,
+        flipVert, flipHoriz
+        """
+        # Get vertices from available attribs
+        if hasattr(self, '_tesselVertices'):
+            # Shapes need to render from this
+            verts = self._tesselVertices
+        elif hasattr(self, "_vertices"):
+            # Non-shapes should use base vertices object
+            verts = self._vertices
+        else:
+            # We'll settle for base verts array
+            verts = self.vertices
+
+        # Convert to a vertices object if not already
+        if not isinstance(verts, Vertices):
+            verts = Vertices(verts, obj=self)
+
+        # If needed, sub in missing values for flip and anchor
+        if hasattr(self, "flip"):
+            verts.flip = self.flip
+        if hasattr(self, "anchor"):
+            verts.anchor = self.anchor
+        # Supply current object's pos and size objects
+        verts._size = self._size
+        verts._pos = self._pos
+        # Apply rotation
+        verts = (verts.pix - self._pos.pix).dot(self._rotationMatrix) + self._pos.pix
+        if hasattr(self, "_vertices"):
+            borderVerts = (self._vertices.pix - self._pos.pix).dot(self._rotationMatrix) + self._pos.pix
+        else:
+            borderVerts = verts
+        # Set values
+        self.__dict__['verticesPix'] = verts
+        self.__dict__['_borderPix'] = borderVerts
+        # Mark as updated
+        self._needVertexUpdate = False
+        self._needUpdate = True  # but we presumably need to update the list
+
+    def contains(self, x, y=None, units=None):
+        """Returns True if a point x,y is inside the stimulus' border.
+
+        Can accept variety of input options:
+            + two separate args, x and y
+            + one arg (list, tuple or array) containing two vals (x,y)
+            + an object with a getPos() method that returns x,y, such
+                as a :class:`~psychopy.event.Mouse`.
+
+        Returns `True` if the point is within the area defined either by its
+        `border` attribute (if one defined), or its `vertices` attribute if
+        there is no .border. This method handles
+        complex shapes, including concavities and self-crossings.
+
+        Note that, if your stimulus uses a mask (such as a Gaussian) then
+        this is not accounted for by the `contains` method; the extent of the
+        stimulus is determined purely by the size, position (pos), and
+        orientation (ori) settings (and by the vertices for shape stimuli).
+
+        See Coder demos: shapeContains.py
+        See Coder demos: shapeContains.py
+        """
+        # get the object in pixels
+        if hasattr(x, 'border'):
+            xy = x._borderPix  # access only once - this is a property
+            units = 'pix'  # we can forget about the units
+        elif hasattr(x, 'verticesPix'):
+            # access only once - this is a property (slower to access)
+            xy = x.verticesPix
+            units = 'pix'  # we can forget about the units
+        elif hasattr(x, 'getPos'):
+            xy = x.getPos()
+            units = x.units
+        elif type(x) in [list, tuple, numpy.ndarray]:
+            xy = numpy.array(x)
+        else:
+            xy = numpy.array((x, y))
+        # try to work out what units x,y has
+        if units is None:
+            if hasattr(xy, 'units'):
+                units = xy.units
+            else:
+                units = self.units
+        if units != 'pix':
+            xy = convertToPix(xy, pos=(0, 0), units=units, win=self.win)
+        # ourself in pixels
+        if hasattr(self, 'border'):
+            poly = self._borderPix  # e.g., outline vertices
+        elif hasattr(self, 'boundingBox'):
+            if abs(self.ori) > 0.1:
+                raise RuntimeError("TextStim.contains() doesn't currently "
+                                   "support rotated text.")
+            w, h = self.boundingBox  # e.g., outline vertices
+            x, y = self.posPix
+            poly = numpy.array([[x+w/2, y-h/2], [x-w/2, y-h/2],
+                                [x-w/2, y+h/2], [x+w/2, y+h/2]])
+        else:
+            poly = self.verticesPix  # e.g., tessellated vertices
+
+        return pointInPolygon(xy[0], xy[1], poly=poly)
+
+    def overlaps(self, polygon):
+        """Returns `True` if this stimulus intersects another one.
+
+        If `polygon` is another stimulus instance, then the vertices
+        and location of that stimulus will be used as the polygon.
+        Overlap detection is typically very good, but it
+        can fail with very pointy shapes in a crossed-swords configuration.
+
+        Note that, if your stimulus uses a mask (such as a Gaussian blob)
+        then this is not accounted for by the `overlaps` method; the extent
+        of the stimulus is determined purely by the size, pos, and
+        orientation settings (and by the vertices for shape stimuli).
+
+        See coder demo, shapeContains.py
+        """
+        return polygonsOverlap(self, polygon)
+
+
+class TextureMixin:
+    """Mixin class for visual stim that have textures.
+
+    Could move visual.helpers.setTexIfNoShaders() into here.
+
+    """
+    def _createTexture(self, tex, id, pixFormat, stim, res=128, maskParams=None,
+                       forcePOW2=True, dataType=None, wrapping=True):
+        """Create a new OpenGL 2D image texture.
+
+        Parameters
+        ----------
+        tex : Any
+            Texture data. Value can be anything that resembles image data.
+        id : int or :class:`~pyglet.gl.GLint`
+            Texture ID.
+        pixFormat : :class:`~pyglet.gl.GLenum` or int
+            Pixel format to use, values can be `GL_ALPHA` or `GL_RGB`.
+        stim : Any
+            Stimulus object using the texture.
+        res : int
+            The resolution of the texture (unless a bitmap image is used).
+        maskParams : dict or None
+            Additional parameters to configure the mask used with this texture.
+        forcePOW2 : bool
+            Force the texture to be stored in a square memory area. For grating
+            stimuli (anything that needs multiple cycles) `forcePOW2` should be
+            set to be `True`. Otherwise the wrapping of the texture will not
+            work.
+        dataType : class:`~pyglet.gl.GLenum`, int or None
+            None, `GL_UNSIGNED_BYTE`, `GL_FLOAT`. Only affects image files
+            (numpy arrays will be float).
+        wrapping : bool
+            Enable wrapping of the texture. A texture will be set to repeat (or
+            tile).
+        """
+
+        # transform all variants of `None` to that, simplifies conditions below
+        if isinstance(tex, str) and tex in ["none", "None", "color"]:
+            tex = None
+
+        # Create an intensity texture, ranging -1:1.0
+        notSqr = False  # most of the options will be creating a sqr texture
+        wasImage = False  # change this if image loading works
+        interpolate = stim.interpolate
+        if dataType is None:
+            if pixFormat == GL.GL_RGB:
+                dataType = GL.GL_FLOAT
+            else:
+                dataType = GL.GL_UNSIGNED_BYTE
+
+        # Fill out unspecified portions of maskParams with default values
+        if maskParams is None:
+            maskParams = {}
+        # fringeWidth affects the proportion of the stimulus diameter that is
+        # devoted to the raised cosine.
+        allMaskParams = {'fringeWidth': 0.2, 'sd': 3}
+        allMaskParams.update(maskParams)
+
+        if type(tex) == numpy.ndarray:
+            # handle a numpy array
+            # for now this needs to be an NxN intensity array
+            intensity = tex.astype(numpy.float32)
+            if intensity.max() > 1 or intensity.min() < -1:
+                logging.error('numpy arrays used as textures should be in '
+                              'the range -1(black):1(white)')
+            if len(tex.shape) == 3:
+                wasLum = False
+            else:
+                wasLum = True
+            # is it 1D?
+            if tex.shape[0] == 1:
+                stim._tex1D = True
+                res = tex.shape[1]
+            elif len(tex.shape) == 1 or tex.shape[1] == 1:
+                stim._tex1D = True
+                res = tex.shape[0]
+            else:
+                stim._tex1D = False
+                # check if it's a square power of two
+                maxDim = max(tex.shape)
+                powerOf2 = 2 ** numpy.ceil(numpy.log2(maxDim))
+                if (forcePOW2 and
+                        (tex.shape[0] != powerOf2 or
+                         tex.shape[1] != powerOf2)):
+                    logging.error("Requiring a square power of two (e.g. "
+                                  "16 x 16, 256 x 256) texture but didn't "
+                                  "receive one")
+                res = tex.shape[0]
+
+            dataType = GL.GL_FLOAT
+        elif tex in ("sin", "sqr", "saw", "tri", "sinXsin", "sqrXsqr", "circle",
+                     "gauss", "cross", "radRamp", "raisedCos", None):
+            if tex is None:
+                res = 1
+                wrapping = True  # override any wrapping setting for None
+
+            # compute array of intensity value for desired pattern
+            intensity = createLumPattern(tex, res, None, allMaskParams)
+            wasLum = True
+        else:
+            if isinstance(tex, (str, Path)):
+                # maybe tex is the name of a file:
+                filename = findImageFile(tex, checkResources=True)
+                if not filename:
+                    msg = "Couldn't find image %s; check path? (tried: %s)"
+                    logging.error(msg % (tex, os.path.abspath(tex)))
+                    logging.flush()
+                    raise IOError(msg % (tex, os.path.abspath(tex)))
+                try:
+                    im = Image.open(filename)
+                    im = im.transpose(Image.FLIP_TOP_BOTTOM)
+                except IOError:
+                    msg = "Found file '%s', failed to load as an image"
+                    logging.error(msg % (filename))
+                    logging.flush()
+                    msg = "Found file '%s' [= %s], failed to load as an image"
+                    raise IOError(msg % (tex, os.path.abspath(tex)))
+            elif hasattr(tex, 'getVideoFrame'):  # camera or movie textures
+                # get an image to configure the initial texture store
+                if hasattr(tex, 'frameSize'):
+                    if tex.frameSize is None:
+                        raise RuntimeError(
+                            "`Camera.frameSize` is not yet specified, cannot "
+                            "initialize texture!")
+                    self._origSize = frameSize = tex.frameSize
+                    # empty texture for initialization
+                    blankTexture = numpy.zeros(
+                        (frameSize[0] * frameSize[1] * 3), dtype=numpy.uint8)
+                    im = Image.frombuffer(
+                        'RGB',
+                        frameSize,
+                        blankTexture
+                    ).transpose(Image.FLIP_TOP_BOTTOM)
+                else:
+                    msg = "Failed to initialize texture from camera stream."
+                    logging.error(msg)
+                    logging.flush()
+                    raise AttributeError(msg)
+            else:
+                # can't be a file; maybe its an image already in memory?
+                try:
+                    im = tex.copy().transpose(Image.FLIP_TOP_BOTTOM)
+                except AttributeError:  # nope, not an image in memory
+                    msg = "Couldn't make sense of requested image."
+                    logging.error(msg)
+                    logging.flush()
+                    raise AttributeError(msg)
+            # at this point we have a valid im
+            stim._origSize = im.size
+            wasImage = True
+            # is it 1D?
+            if im.size[0] == 1 or im.size[1] == 1:
+                logging.error("Only 2D textures are supported at the moment")
+            else:
+                maxDim = max(im.size)
+                powerOf2 = int(2**numpy.ceil(numpy.log2(maxDim)))
+                if im.size[0] != powerOf2 or im.size[1] != powerOf2:
+                    if not forcePOW2:
+                        notSqr = True
+                    elif globalVars.nImageResizes < reportNImageResizes:
+                        msg = ("Image '%s' was not a square power-of-two ' "
+                               "'image. Linearly interpolating to be %ix%i")
+                        logging.warning(msg % (tex, powerOf2, powerOf2))
+                        globalVars.nImageResizes += 1
+                        im = im.resize([powerOf2, powerOf2], Image.BILINEAR)
+                    elif globalVars.nImageResizes == reportNImageResizes:
+                        logging.warning("Multiple images have needed resizing"
+                                        " - I'll stop bothering you!")
+                        im = im.resize([powerOf2, powerOf2], Image.BILINEAR)
+
+            # is it Luminance or RGB?
+            if pixFormat == GL.GL_ALPHA and im.mode != 'L':
+                # we have RGB and need Lum
+                wasLum = True
+                im = im.convert("L")  # force to intensity (need if was rgb)
+            elif im.mode == 'L':  # we have lum and no need to change
+                wasLum = True
+                dataType = GL.GL_FLOAT
+            elif pixFormat == GL.GL_RGB:
+                # we want RGB and might need to convert from CMYK or Lm
+                # texture = im.tostring("raw", "RGB", 0, -1)
+                im = im.convert("RGBA")
+                wasLum = False
+            else:
+                raise ValueError('cannot determine if image is luminance or RGB')
+
+            if dataType == GL.GL_FLOAT:
+                # convert from ubyte to float
+                # much faster to avoid division 2/255
+                intensity = numpy.array(im).astype(
+                    numpy.float32) * 0.0078431372549019607 - 1.0
+            else:
+                intensity = numpy.array(im)
+
+        if pixFormat == GL.GL_RGB and wasLum and dataType == GL.GL_FLOAT:
+            # grating stim on good machine
+            # keep as float32 -1:1
+            if (sys.platform != 'darwin' and
+                    stim.win.glVendor.startswith('nvidia')):
+                # nvidia under win/linux might not support 32bit float
+                # could use GL_LUMINANCE32F_ARB here but check shader code?
+                internalFormat = GL.GL_RGB16F_ARB
+            else:
+                # we've got a mac or an ATI card and can handle
+                # 32bit float textures
+                # could use GL_LUMINANCE32F_ARB here but check shader code?
+                internalFormat = GL.GL_RGB32F_ARB
+            # initialise data array as a float
+            data = numpy.ones((intensity.shape[0], intensity.shape[1], 3),
+                              numpy.float32)
+            data[:, :, 0] = intensity  # R
+            data[:, :, 1] = intensity  # G
+            data[:, :, 2] = intensity  # B
+        elif (pixFormat == GL.GL_RGB and
+                wasLum and
+                dataType != GL.GL_FLOAT):
+            # was a lum image: stick with ubyte for speed
+            internalFormat = GL.GL_RGB
+            # initialise data array as a float
+            data = numpy.ones((intensity.shape[0], intensity.shape[1], 3),
+                              numpy.ubyte)
+            data[:, :, 0] = intensity  # R
+            data[:, :, 1] = intensity  # G
+            data[:, :, 2] = intensity  # B
+        elif pixFormat == GL.GL_RGB and dataType == GL.GL_FLOAT:
+            # probably a custom rgb array or rgb image
+            internalFormat = GL.GL_RGB32F_ARB
+            data = intensity
+        elif pixFormat == GL.GL_RGB:
+            # not wasLum, not useShaders  - an RGB bitmap with no shader
+            #  optionsintensity.min()
+            internalFormat = GL.GL_RGB
+            data = intensity  # float_uint8(intensity)
+        elif pixFormat == GL.GL_ALPHA:
+            internalFormat = GL.GL_ALPHA
+            dataType = GL.GL_UNSIGNED_BYTE
+            if wasImage:
+                data = intensity
+            else:
+                data = float_uint8(intensity)
+        else:
+            raise ValueError("invalid or unsupported `pixFormat`")
+
+        # check for RGBA textures
+        if len(data.shape) > 2 and data.shape[2] == 4:
+            if pixFormat == GL.GL_RGB:
+                pixFormat = GL.GL_RGBA
+            if internalFormat == GL.GL_RGB:
+                internalFormat = GL.GL_RGBA
+            elif internalFormat == GL.GL_RGB32F_ARB:
+                internalFormat = GL.GL_RGBA32F_ARB
+        texture = data.ctypes  # serialise
+
+        # Create the pixel buffer object which will serve as the texture memory
+        # store. First we compute the number of bytes used to store the texture.
+        # We need to determine the data type in use by the texture to do this.
+        if stim is not None and hasattr(stim, '_pixbuffID'):
+            if dataType == GL.GL_UNSIGNED_BYTE:
+                storageType = GL.GLubyte
+            elif dataType == GL.GL_FLOAT:
+                storageType = GL.GLfloat
+            else:
+                # raise waring or error? just default to `GLfloat` for now
+                storageType = GL.GLfloat
+
+            # compute buffer size
+            bufferSize = data.size * ctypes.sizeof(storageType)
+
+            # create the pixel buffer to access texture memory as an array
+            GL.glBindBuffer(GL.GL_PIXEL_UNPACK_BUFFER, stim._pixbuffID)
+            GL.glBufferData(
+                GL.GL_PIXEL_UNPACK_BUFFER,
+                bufferSize,
+                None,
+                GL.GL_STREAM_DRAW)  # one-way app -> GL
+            GL.glBindBuffer(GL.GL_PIXEL_UNPACK_BUFFER, 0)
+
+        # bind the texture in openGL
+        GL.glEnable(GL.GL_TEXTURE_2D)
+        GL.glBindTexture(GL.GL_TEXTURE_2D, id)  # bind that name to the target
+        # makes the texture map wrap (this is actually default anyway)
+        if wrapping:
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_WRAP_S, GL.GL_REPEAT)
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_WRAP_T, GL.GL_REPEAT)
+        else:
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_WRAP_S, GL.GL_CLAMP)
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_WRAP_T, GL.GL_CLAMP)
+        # data from PIL/numpy is packed, but default for GL is 4 bytes
+        GL.glPixelStorei(GL.GL_UNPACK_ALIGNMENT, 1)
+        # important if using bits++ because GL_LINEAR
+        # sometimes extrapolates to pixel vals outside range
+        if interpolate:
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_MAG_FILTER, GL.GL_LINEAR)
+            # GL_GENERATE_MIPMAP was only available from OpenGL 1.4
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_MIN_FILTER, GL.GL_LINEAR)
+            GL.glTexParameteri(GL.GL_TEXTURE_2D, GL.GL_GENERATE_MIPMAP,
+                               GL.GL_TRUE)
+            GL.glTexImage2D(GL.GL_TEXTURE_2D, 0, internalFormat,
+                            data.shape[1], data.shape[0], 0,
+                            pixFormat, dataType, texture)
+        else:
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_MAG_FILTER, GL.GL_NEAREST)
+            GL.glTexParameteri(
+                GL.GL_TEXTURE_2D, GL.GL_TEXTURE_MIN_FILTER, GL.GL_NEAREST)
+            GL.glTexImage2D(GL.GL_TEXTURE_2D, 0, internalFormat,
+                            data.shape[1], data.shape[0], 0,
+                            pixFormat, dataType, texture)
+
+        GL.glTexEnvi(GL.GL_TEXTURE_ENV, GL.GL_TEXTURE_ENV_MODE,
+                     GL.GL_MODULATE)  # ?? do we need this - think not!
+        # unbind our texture so that it doesn't affect other rendering
+        GL.glBindTexture(GL.GL_TEXTURE_2D, 0)
+
+        return wasLum
+
+    def clearTextures(self):
+        """Clear all textures associated with the stimulus.
+
+        As of v1.61.00 this is called automatically during garbage collection
+        of your stimulus, so doesn't need calling explicitly by the user.
+        """
+        if hasattr(self, '_texID'):
+            GL.glDeleteTextures(1, self._texID)
+
+        if hasattr(self, '_maskID'):
+            GL.glDeleteTextures(1, self._maskID)
+
+        if hasattr(self, '_pixBuffID'):
+            GL.glDeleteBuffers(1, self._pixBuffID)
+
+    @attributeSetter
+    def mask(self, value):
+        """The alpha mask (forming the shape of the image).
+
+        This can be one of various options:
+            * 'circle', 'gauss', 'raisedCos', 'cross'
+            * **None** (resets to default)
+            * the name of an image file (most formats supported)
+            * a numpy array (1xN or NxN) ranging -1:1
+
+        """
+        self.__dict__['mask'] = value
+        if self.__class__.__name__ == 'ImageStim':
+            dataType = GL.GL_UNSIGNED_BYTE
+        else:
+            dataType = None
+        self._createTexture(
+            value, id=self._maskID, pixFormat=GL.GL_ALPHA, dataType=dataType,
+            stim=self, res=self.texRes, maskParams=self.maskParams,
+            wrapping=False)
+
+    def setMask(self, value, log=None):
+        """Usually you can use 'stim.attribute = value' syntax instead,
+        but use this method if you need to suppress the log message.
+        """
+        setAttribute(self, 'mask', value, log)
+
+    @attributeSetter
+    def texRes(self, value):
+        """Power-of-two int. Sets the resolution of the mask and texture.
+        texRes is overridden if an array or image is provided as mask.
+
+        :ref:`Operations <attrib-operations>` supported.
+        """
+        self.__dict__['texRes'] = value
+
+        # ... now rebuild textures (call attributeSetters without logging).
+        if hasattr(self, 'tex'):
+            setAttribute(self, 'tex', self.tex, log=False)
+        if hasattr(self, 'mask'):
+            setAttribute(self, 'mask', self.mask, log=False)
+
+    @attributeSetter
+    def maskParams(self, value):
+        """Various types of input. Default to `None`.
+
+        This is used to pass additional parameters to the mask if those are
+        needed.
+
+            - For 'gauss' mask, pass dict {'sd': 5} to control
+                standard deviation.
+            - For the 'raisedCos' mask, pass a dict: {'fringeWidth':0.2},
+                where 'fringeWidth' is a parameter (float, 0-1), determining
+                the proportion of the patch that will be blurred by the raised
+                cosine edge."""
+        self.__dict__['maskParams'] = value
+        # call attributeSetter without log
+        setAttribute(self, 'mask', self.mask, log=False)
+
+    @attributeSetter
+    def interpolate(self, value):
+        """Whether to interpolate (linearly) the texture in the stimulus.
+
+        If set to False then nearest neighbour will be used when needed,
+        otherwise some form of interpolation will be used.
+        """
+        self.__dict__['interpolate'] = value
+
+
+class WindowMixin:
+    """Window-related attributes and methods.
+
+    Used by BaseVisualStim, SimpleImageStim and ElementArrayStim.
+
+    """
+    @property
+    def win(self):
+        """The :class:`~psychopy.visual.Window` object in which the
+        stimulus will be rendered by default. (required)
+
+        Example, drawing same stimulus in two different windows and display
+        simultaneously. Assuming that you have two windows and a stimulus
+        (win1, win2 and stim)::
+
+           stim.win = win1  # stimulus will be drawn in win1
+           stim.draw()  # stimulus is now drawn to win1
+           stim.win = win2  # stimulus will be drawn in win2
+           stim.draw()  # it is now drawn in win2
+           win1.flip(waitBlanking=False)  # do not wait for next
+                        # monitor update
+           win2.flip()  # wait for vertical blanking.
+
+        Note that this just changes **default** window for stimulus.
+
+        You could also specify window-to-draw-to when drawing::
+
+           stim.draw(win1)
+           stim.draw(win2)
+
+        """
+        return self.__dict__['win']
+
+    @win.setter
+    def win(self, value):
+        self.__dict__['win'] = value
+        # Update window ref in size and pos objects
+        if hasattr(self, "_size") and isinstance(self._size, Vector):
+            self._size.win = value
+        if hasattr(self, "_pos") and isinstance(self._pos, Vector):
+            self._pos.win = value
+
+    @property
+    def pos(self):
+        if hasattr(self, "_pos"):
+            return getattr(self._pos, self.units)
+
+    @pos.setter
+    def pos(self, value):
+        # If no autolog attribute, assume silent
+        if hasattr(self, "autoLog"):
+            log = self.autoLog
+        else:
+            log = False
+        # Do attribute setting
+        setAttribute(self, '_pos', Position(value, units=self.units, win=self.win), log)
+
+        if hasattr(self, "_vertices"):
+            self._vertices._pos = self._pos
+
+        if hasattr(self, "_vertices"):
+            self._vertices._pos = self._pos
+
+    @property
+    def size(self):
+        if hasattr(self, "_size"):
+            return getattr(self._size, self.units)
+
+    @size.setter
+    def size(self, value):
+        # Convert None to a 2x1 tuple
+        if value is None:
+            value = (None, None)
+        # If no autolog attribute, assume silent
+        if hasattr(self, "autoLog"):
+            log = self.autoLog
+        else:
+            log = False
+        # Do attribute setting
+        setAttribute(self, '_size', Size(value, units=self.units, win=self.win), log)
+
+        if hasattr(self, "_vertices"):
+            self._vertices._size = self._size
+
+        if hasattr(self, "_vertices"):
+            self._vertices._size = self._size
+
+    @property
+    def width(self):
+        if len(self.size.shape) == 1:
+            # Return first value if a 1d array
+            return self.size[0]
+        elif len(self.size.shape) == 2:
+            # Return first column if a 2d array
+            return self.size[:, 0]
+
+    @width.setter
+    def width(self, value):
+        # Convert to a numpy array
+        value = numpy.array(value)
+        # Get original size
+        size = self.size
+        # Set size
+        if len(self.size.shape) == 1:
+            # Set first value if a 1d array
+            size[0] = value
+        elif len(self.size.shape) == 2:
+            # Set first column if a 2d array
+            size[:, 0] = value
+        else:
+            raise NotImplementedError(
+                f"Cannot set height and width for {type(self).__name__} objects with more than 2 dimensions. "
+                f"Please use .size instead."
+            )
+
+        self.size = size
+
+    @property
+    def height(self):
+        if len(self.size.shape) == 1:
+            # Return first value if a 1d array
+            return self.size[1]
+        elif len(self.size.shape) == 2:
+            # Return first column if a 2d array
+            return self.size[:, 1]
+
+    @height.setter
+    def height(self, value):
+        # Convert to a numpy array
+        value = numpy.array(value)
+        # Get original size
+        size = self.size
+        # Set size
+        if len(self.size.shape) == 1:
+            # Set second value if a 1d array
+            size[1] = value
+        elif len(self.size.shape) == 2:
+            # Set second column if a 2d array
+            size[:, 1] = value
+        else:
+            raise NotImplementedError(
+                f"Cannot set height and width for {type(self).__name__} objects with more than 2 dimensions. "
+                f"Please use .size instead."
+            )
+
+        self.size = size
+
+    @property
+    def vertices(self):
+        # Get or make Vertices object
+        if hasattr(self, "_vertices"):
+            verts = self._vertices
+        else:
+            # If not defined, assume vertices are just a square
+            verts = self._vertices = Vertices(numpy.array([
+                                [0.5, -0.5],
+                                [-0.5, -0.5],
+                                [-0.5, 0.5],
+                                [0.5, 0.5],
+                            ]), obj=self, flip=self.flip, anchor=self.anchor)
+        return verts.base
+
+    @vertices.setter
+    def vertices(self, value):
+        # If None, use defaut
+        if value is None:
+            value = [
+                [0.5, -0.5],
+                [-0.5, -0.5],
+                [-0.5, 0.5],
+                [0.5, 0.5],
+            ]
+        # Create Vertices object
+        self._vertices = Vertices(value, obj=self, flip=self.flip, anchor=self.anchor)
+        self._needVertexUpdate = True
+
+    @property
+    def flip(self):
+        """
+        1x2 array for flipping vertices along each axis; set as True to flip or False to not flip. If set as a single value, will duplicate across both axes. Accessing the protected attribute (`._flip`) will give an array of 1s and -1s with which to multiply vertices.
+        """
+        # Get base value
+        if hasattr(self, "_flip"):
+            flip = self._flip
+        else:
+            flip = numpy.array([[False, False]])
+        # Convert from boolean
+        return flip == -1
+
+    @flip.setter
+    def flip(self, value):
+        if value is None:
+            value = False
+        # Convert to 1x2 numpy array
+        value = numpy.array(value)
+        value.resize((1, 2))
+        # Ensure values were bool
+        assert value.dtype == bool, "Flip values must be either a boolean (True/False) or an array of booleans"
+        # Set as multipliers rather than bool
+        self._flip = numpy.array([[
+            -1 if value[0, 0] else 1,
+            -1 if value[0, 1] else 1,
+        ]])
+        self._flipHoriz, self._flipVert = self._flip[0]
+        # Apply to vertices
+        if not hasattr(self, "_vertices"):
+            self.vertices = None
+        self._vertices.flip = self.flip
+        # Mark as needing vertex update
+        self._needVertexUpdate = True
+
+    @property
+    def flipHoriz(self):
+        return self.flip[0][0]
+
+    @flipHoriz.setter
+    def flipHoriz(self, value):
+        self.flip = [value, self.flip[0, 1]]
+
+    @property
+    def flipVert(self):
+        return self.flip[0][1]
+
+    @flipVert.setter
+    def flipVert(self, value):
+        self.flip = [self.flip[0, 0], value]
+
+    @property
+    def anchor(self):
+        if hasattr(self, "_vertices"):
+            return self._vertices.anchor
+        elif hasattr(self, "_anchor"):
+            # Return a backup value if there's no vertices yet
+            return self._anchor
+
+    @anchor.setter
+    def anchor(self, value):
+        if hasattr(self, "_vertices"):
+            self._vertices.anchor = value
+        else:
+            # Set a backup value if there's no vertices yet
+            self._anchor = value
+
+    def setAnchor(self, value, log=None):
+        setAttribute(self, 'anchor', value, log)
+
+    @property
+    def units(self):
+        if hasattr(self, "_units"):
+            return self._units
+        else:
+            return self.win.units
+
+    @units.setter
+    def units(self, value):
+        """
+        Units to use when drawing.
+
+        Possible options are: None, 'norm', 'cm', 'deg', 'degFlat',
+        'degFlatPos', or 'pix'.
+
+        If None then the current units of the
+        :class:`~psychopy.visual.Window` will be used.
+        See :ref:`units` for explanation of other options.
+
+        Note that when you change units, you don't change the stimulus
+        parameters and it is likely to change appearance.
+
+        Example::
+
+            # This stimulus is 20% wide and 50% tall with respect to window
+            stim = visual.PatchStim(win, units='norm', size=(0.2, 0.5)
+
+            # This stimulus is 0.2 degrees wide and 0.5 degrees tall.
+            stim.units = 'deg'
+
+        """
+        if value in unitTypes:
+            self._units = value or self.win.units
+            self._needVertexUpdate = True
+        else:
+            raise ValueError(f"Invalid unit type '{value}', must be one of: {unitTypes}")
+
+    def draw(self):
+        raise NotImplementedError('Stimulus classes must override '
+                                  'visual.BaseVisualStim.draw')
+
+    def _selectWindow(self, win):
+        """Switch drawing to the specified window. Calls the window's
+        _setCurrent() method which handles the switch.
+        """
+        win._setCurrent()
+
+    def _updateList(self):
+        """The user shouldn't need this method since it gets called
+        after every call to .set()
+        Chooses between using and not using shaders each call.
+        """
+        self._updateListShaders()
+
+
+class DraggingMixin:
+    """
+    Mixin to give an object innate dragging behaviour.
+
+    Attributes
+    ==========
+    draggable : bool
+        Can this object be dragged by a Mouse click?
+    isDragging : bool
+        Is this object currently being dragged? (read only)
+
+    Methods
+    ==========
+    doDragging :
+        Call this each frame to make sure dragging behaviour happens. If
+        `autoDraw` and `draggable` are both True, then this will be called
+        automatically by the Window object on flip.
+    """
+    isDragging = False
+
+    def doDragging(self):
+        """
+        If this stimulus is draggable, do the necessary actions on a frame
+        flip to drag it.
+        """
+        # if not draggable, do nothing
+        if not self.draggable:
+            return
+        # if something else is already dragging, do nothing
+        if self.win.currentDraggable is not None and self.win.currentDraggable != self:
+            return
+        # if just clicked on, start dragging
+        self.isDragging = self.isDragging or self.mouse.isPressedIn(self, buttons=[0])
+        # if click is released, stop dragging
+        self.isDragging = self.isDragging and self.mouse.getPressed()[0]
+        # get relative mouse pos
+        rel = self.mouse.getRel()
+
+        # if dragging, do necessary updates
+        if self.isDragging:
+            # set as current draggable
+            self.win.currentDraggable = self
+            # get own pos in win units
+            pos = getattr(self._pos, self.win.units)
+            # add mouse movement to pos
+            setattr(
+                self._pos,
+                self.win.units,
+                pos + rel
+            )
+            # set pos
+            self.pos = getattr(self._pos, self.units)
+        else:
+            # remove as current draggable
+            self.win.currentDraggable = None
+
+    @attributeSetter
+    def draggable(self, value):
+        """
+        Can this stimulus be dragged by a mouse click?
+        """
+        # if we don't have reference to a mouse, make one
+        if not isinstance(self.mouse, Mouse):
+            self.mouse = Mouse(win=self.win)
+            # make sure it has an initial pos for rel pos comparisons
+            self.mouse.lastPos = self.mouse.getPos()
+        # store value
+        self.__dict__['draggable'] = value
+
+
+class BaseVisualStim(MinimalStim, WindowMixin, LegacyVisualMixin):
+    """A template for a visual stimulus class.
+
+    Actual visual stim like GratingStim, TextStim etc... are based on this.
+    Not finished...?
+
+    Methods defined here will override Minimal & Legacy, but best to avoid
+    that for simplicity & clarity.
+
+    """
+    def __init__(self, win, units=None, name='', autoLog=None):
+        self.autoLog = False  # just to start off during init, set at end
+        self.win = win
+        self.units = units
+        self._rotationMatrix = [[1., 0.], [0., 1.]]  # no rotation by default
+        self.mouse = None
+        # self.autoLog is set at end of MinimalStim.__init__
+        super(BaseVisualStim, self).__init__(name=name, autoLog=autoLog)
+        if self.autoLog:
+            msg = ("%s is calling BaseVisualStim.__init__() with autolog=True"
+                   ". Set autoLog to True only at the end of __init__())")
+            logging.warning(msg % (self.__class__.__name__))
+
+    @property
+    def opacity(self):
+        """Determines how visible the stimulus is relative to background.
+
+        The value should be a single float ranging 1.0 (opaque) to 0.0
+        (transparent). :ref:`Operations <attrib-operations>` are supported.
+        Precisely how this is used depends on the :ref:`blendMode`.
+        """
+        alphas = []
+        if hasattr(self, '_foreColor'):
+            alphas.append(self._foreColor.alpha)
+        if hasattr(self, '_fillColor'):
+            alphas.append(self._fillColor.alpha)
+        if hasattr(self, '_borderColor'):
+            alphas.append(self._borderColor.alpha)
+        if alphas:
+            return mean(alphas)
+        else:
+            return 1
+
+    @opacity.setter
+    def opacity(self, value):
+        # Setting opacity as a single value makes all colours the same opacity
+        if value is None:
+            # If opacity is set to be None, this indicates that each color should handle its own opacity
+            return
+        if hasattr(self, '_foreColor'):
+            if self._foreColor != None:
+                self._foreColor.alpha = value
+        if hasattr(self, '_fillColor'):
+            if self._fillColor != None:
+                self._fillColor.alpha = value
+        if hasattr(self, '_borderColor'):
+            if self._borderColor != None:
+                self._borderColor.alpha = value
+
+    def updateOpacity(self):
+        """Placeholder method to update colours when set externally, for example
+        updating the `pallette` attribute of a textbox."""
+        return
+
+    @attributeSetter
+    def ori(self, value):
+        """The orientation of the stimulus (in degrees).
+
+        Should be a single value (:ref:`scalar <attrib-scalar>`).
+        :ref:`Operations <attrib-operations>` are supported.
+
+        Orientation convention is like a clock: 0 is vertical, and positive
+        values rotate clockwise. Beyond 360 and below zero values wrap
+        appropriately.
+
+        """
+        self.__dict__['ori'] = float(value)
+        radians = value * 0.017453292519943295
+        sin, cos = numpy.sin, numpy.cos
+        self._rotationMatrix = numpy.array([[cos(radians), -sin(radians)],
+                                            [sin(radians), cos(radians)]])
+        self._needVertexUpdate = True  # need to update update vertices
+        self._needUpdate = True
+
+    @property
+    def size(self):
+        """The size (width, height) of the stimulus in the stimulus
+        :ref:`units <units>`
+
+        Value should be :ref:`x,y-pair <attrib-xy>`,
+        :ref:`scalar <attrib-scalar>` (applies to both dimensions)
+        or None (resets to default). :ref:`Operations <attrib-operations>`
+        are supported.
+
+        Sizes can be negative (causing a mirror-image reversal) and can
+        extend beyond the window.
+
+        Example::
+
+            stim.size = 0.8  # Set size to (xsize, ysize) = (0.8, 0.8)
+            print(stim.size)  # Outputs array([0.8, 0.8])
+            stim.size += (0.5, -0.5)  # make wider and flatter: (1.3, 0.3)
+
+        Tip: if you can see the actual pixel range this corresponds to by
+        looking at `stim._sizeRendered`
+        """
+        return WindowMixin.size.fget(self)
+
+    @size.setter
+    def size(self, value):
+        # Supply default for None
+        if value is None:
+            value = Size((1, 1), units="height", win=self.win)
+        # Duplicate single values
+        if isinstance(value, (float, int)):
+            value = (value, value)
+        # Do setting
+        WindowMixin.size.fset(self, value)
+        # Mark any updates needed
+        self._needVertexUpdate = True
+        self._needUpdate = True
+        if hasattr(self, '_calcCyclesPerStim'):
+            self._calcCyclesPerStim()
+
+    @property
+    def pos(self):
+        """
+        The position of the center of the stimulus in the stimulus
+        :ref:`units <units>`
+
+        `value` should be an :ref:`x,y-pair <attrib-xy>`.
+        :ref:`Operations <attrib-operations>` are also supported.
+
+        Example::
+
+            stim.pos = (0.5, 0)  # Set slightly to the right of center
+            stim.pos += (0.5, -1)  # Increment pos rightwards and upwards.
+                Is now (1.0, -1.0)
+            stim.pos *= 0.2  # Move stim towards the center.
+                Is now (0.2, -0.2)
+
+        Tip: If you need the position of stim in pixels, you can obtain
+        it like this::
+
+            from psychopy.tools.monitorunittools import posToPix
+            posPix = posToPix(stim)
+
+        """
+        return WindowMixin.pos.fget(self)
+
+    @pos.setter
+    def pos(self, value):
+        # Supply defualt for None
+        if value is None:
+            value = Position((0, 0), units="height", win=self.win)
+        # Do setting
+        WindowMixin.pos.fset(self, value)
+        # Mark any updates needed
+        self._needVertexUpdate = True
+        self._needUpdate = True
+
+    def setPos(self, newPos, operation='', log=None):
+        """Usually you can use 'stim.attribute = value' syntax instead,
+        but use this method if you need to suppress the log message.
+        """
+        setAttribute(self, 'pos', val2array(newPos, False), log, operation)
+
+    def setDepth(self, newDepth, operation='', log=None):
+        """Usually you can use 'stim.attribute = value' syntax instead,
+        but use this method if you need to suppress the log message
+        """
+        setAttribute(self, 'depth', newDepth, log, operation)
+
+    def setSize(self, newSize, operation='', units=None, log=None):
+        """Usually you can use 'stim.attribute = value' syntax instead,
+        but use this method if you need to suppress the log message
+        """
+        if units is None:
+            # need to change this to create several units from one
+            units = self.units
+        # If we have an original size (e.g. for an image or movie), then we CAN set size with None
+        useNone = hasattr(self, "origSize")
+        # Set attribute
+        setAttribute(self, 'size', val2array(newSize, useNone), log, operation)
+
+    def setOri(self, newOri, operation='', log=None):
+        """Usually you can use 'stim.attribute = value' syntax instead,
+        but use this method if you need to suppress the log message
+        """
+        setAttribute(self, 'ori', newOri, log, operation)
+
+    def setOpacity(self, newOpacity, operation='', log=None):
+        """Hard setter for opacity, allows the suppression of log messages and calls the update method
+        """
+        if operation in ['', '=']:
+            self.opacity = newOpacity
+        elif operation in ['+']:
+            self.opacity += newOpacity
+        elif operation in ['-']:
+            self.opacity -= newOpacity
+        else:
+            logging.error(f"Operation '{operation}' not recognised.")
+        # Trigger color update for components like Textbox which have different behaviours for a hard setter
+        self.updateOpacity()
+
+    def _set(self, attrib, val, op='', log=None):
+        """DEPRECATED since 1.80.04 + 1.
+        Use setAttribute() and val2array() instead.
+        """
+        # format the input value as float vectors
+        if type(val) in [tuple, list, numpy.ndarray]:
+            val = val2array(val, length=len(val))
+
+        # Set attribute with operation and log
+        setAttribute(self, attrib, val, log, op)
+
+        # For DotStim
+        if attrib in ('nDots', 'coherence'):
+            self.coherence = round(self.coherence * self.nDots) / self.nDots