# -*- coding: utf-8 -*-
# Copyright (c) Vispy Development Team. All Rights Reserved.
# Distributed under the (new) BSD License. See LICENSE.txt for more info.
"""

Definitions
===========

Visual : an object that (1) can be drawn on-screen, (2) can be manipulated
by configuring the coordinate transformations that it uses.

View : a special type of visual that (1) draws the contents of another visual,
(2) using a different set of transforms. Views have only the basic visual
interface (draw, bounds, attach, etc.) and lack access to the specific features
of the visual they are linked to (for example, LineVisual has a ``set_data()``
method, but there is no corresponding method on a view of a LineVisual).


Class Structure
===============

* `BaseVisual` - provides transforms and view creation
  This class lays out the basic API for all visuals: ``draw()``, ``bounds()``,
  ``view()``, and ``attach()`` methods, as well as a `TransformSystem` instance
  that determines where the visual will be drawn.
* `Visual` - defines a shader program to draw.
  Subclasses are responsible for supplying the shader code and configuring
  program variables, including transforms.
* `VisualView` - clones the shader program from a Visual instance.
  Instances of `VisualView` contain their own shader program,
  transforms and filter attachments, and generally behave like a normal
  instance of `Visual`.
* `CompoundVisual` - wraps multiple Visual instances.
  These visuals provide no program of their own, but instead rely on one or
  more internally generated `Visual` instances to do their drawing. For
  example, a PolygonVisual consists of an internal LineVisual and
  MeshVisual.
* `CompoundVisualView` - wraps multiple VisualView instances.
  This allows a `CompoundVisual` to be viewed with a different set of
  transforms and filters.


Making Visual Subclasses
========================

When making subclasses of `Visual`, it is only necessary to reimplement the
``_prepare_draw()``, ``_prepare_transforms()``, and ``_compute_bounds()``
methods. These methods will be called by the visual automatically when it is
needed for itself or for a view of the visual.

It is important to remember
when implementing these methods that most changes made to the visual's shader
program should also be made to the programs for each view. To make this easier,
the visual uses a `MultiProgram`, which allows all shader programs across the
visual and its views to be accessed simultaneously. For example::

    def _prepare_draw(self, view):
        # This line applies to the visual and all of its views
        self.shared_program['a_position'] = self._vbo

        # This line applies only to the view that is about to be drawn
        view.view_program['u_color'] = (1, 1, 1, 1)

Under most circumstances, it is not necessary to reimplement `VisualView`
because a view will directly access the ``_prepare`` and ``_compute`` methods
from the visual it is viewing. However, if the `Visual` to be viewed is a
subclass that reimplements other methods such as ``draw()`` or ``bounds()``,
then it will be necessary to provide a new matching `VisualView` subclass.


Making CompoundVisual Subclasses
================================

Compound visual subclasses are generally very easy to construct::

    class PlotLineVisual(visuals.CompoundVisual):
        def __init__(self, ...):
            self._line = LineVisual(...)
            self._point = PointVisual(...)
            visuals.CompoundVisual.__init__(self, [self._line, self._point])

A compound visual will automatically handle forwarding transform system changes
and filter attachments to its internally-wrapped visuals. To the user, this
will appear to behave as a single visual.
"""
from __future__ import division
import weakref
from contextlib import contextmanager

import numpy as np

from .. import gloo
from ..util.event import EmitterGroup, Event
from ..util import logger, Frozen
from .shaders import StatementList, MultiProgram
from .transforms import TransformSystem


class VisualShare(object):
    """Contains data that is shared between all views of a visual.

    This includes:

        * GL state variables (blending, depth test, etc.)
        * A weak dictionary of all views
        * A list of filters that should be applied to all views
        * A cache for bounds.

    """

    def __init__(self):
        # Note: in some cases we will need to compute bounds independently for
        # each view. That will have to be worked out later..
        self.bounds = {}
        self.gl_state = {}
        self.views = weakref.WeakKeyDictionary()
        self.filters = []
        self.visible = True


class BaseVisual(Frozen):
    """Superclass for all visuals.

    This class provides:

        * A TransformSystem.
        * Two events: `update` and `bounds_change`.
        * Minimal framework for creating views of the visual.
        * A data structure that is shared between all views of the visual.
        * Abstract `draw`, `bounds`, `attach`, and `detach` methods.

    Parameters
    ----------
    vshare : instance of VisualShare | None
        The visual share.

    Notes
    -----
    When used in the scenegraph, all Visual classes are mixed with
    `vispy.scene.Node` in order to implement the methods, attributes and
    capabilities required for their usage within it.

    This subclasses Frozen so that subclasses can easily freeze their
    properties.
    """

    def __init__(self, vshare=None):
        self._view_class = getattr(self, '_view_class', VisualView)

        self._vshare = VisualShare() if vshare is None else vshare
        self._vshare.views[self] = None

        self.events = EmitterGroup(source=self,
                                   auto_connect=True,
                                   update=Event,
                                   bounds_change=Event
                                   )

        self._transforms = None
        self.transforms = TransformSystem()

    @property
    def transform(self):
        return self.transforms.visual_transform.transforms[0]

    @transform.setter
    def transform(self, tr):
        self.transforms.visual_transform = tr

    @property
    def transforms(self):
        return self._transforms

    @transforms.setter
    def transforms(self, trs):
        if trs is self._transforms:
            return
        if self._transforms is not None:
            self._transforms.changed.disconnect(self._transform_changed)
        self._transforms = trs
        trs.changed.connect(self._transform_changed)
        self._transform_changed()

    def get_transform(self, map_from='visual', map_to='render'):
        """Return a transform mapping between any two coordinate systems.

        Parameters
        ----------
        map_from : str
            The starting coordinate system to map from. Must be one of: visual,
            scene, document, canvas, framebuffer, or render.
        map_to : str
            The ending coordinate system to map to. Must be one of: visual,
            scene, document, canvas, framebuffer, or render.
        """
        return self.transforms.get_transform(map_from, map_to)

    @property
    def visible(self):
        return self._vshare.visible

    @visible.setter
    def visible(self, v):
        if v != self._vshare.visible:
            self._vshare.visible = v
            self.update()

    def view(self):
        """Return a new view of this visual."""
        return self._view_class(self)

    def draw(self):
        raise NotImplementedError(self)

    def attach(self, filt, view=None):
        """Attach a Filter to this visual.

        Each filter modifies the appearance or behavior of the visual.

        Parameters
        ----------
        filt : object
            The filter to attach.
        view : instance of VisualView | None
            The view to use.
        """
        raise NotImplementedError(self)

    def detach(self, filt, view=None):
        """Detach a filter.

        Parameters
        ----------
        filt : object
            The filter to detach.
        view : instance of VisualView | None
            The view to use.
        """
        raise NotImplementedError(self)

    def bounds(self, axis, view=None):
        """Get the bounds of the Visual

        Parameters
        ----------
        axis : int
            The axis.
        view : instance of VisualView
            The view to use.
        """
        if view is None:
            view = self
        if axis not in self._vshare.bounds:
            self._vshare.bounds[axis] = self._compute_bounds(axis, view)
        return self._vshare.bounds[axis]

    def _compute_bounds(self, axis, view):
        raise NotImplementedError(self)

    def _bounds_changed(self):
        self._vshare.bounds.clear()

    def update(self):
        """Update the Visual"""
        self.events.update()

    def _transform_changed(self, event=None):
        self.update()


class BaseVisualView(object):
    """Base class for a view on a visual.

    This class must be mixed with another Visual class to work properly. It
    works mainly by forwarding the calls to _prepare_draw, _prepare_transforms,
    and _compute_bounds to the viewed visual.
    """

    def __init__(self, visual):
        self._visual = visual

    @property
    def visual(self):
        return self._visual

    def _prepare_draw(self, view=None):
        self._visual._prepare_draw(view=view)

    def _prepare_transforms(self, view):
        self._visual._prepare_transforms(view)

    def _compute_bounds(self, axis, view):
        self._visual._compute_bounds(axis, view)

    def __repr__(self):
        return '<%s on %r>' % (self.__class__.__name__, self._visual)


class Visual(BaseVisual):
    """Base class for all visuals that can be drawn using a single shader
    program.

    This class creates a MultiProgram, which is an object that
    behaves like a normal shader program (you can assign shader code, upload
    values, set template variables, etc.) but internally manages multiple
    ModularProgram instances, one per view.

    Subclasses generally only need to reimplement _compute_bounds,
    _prepare_draw, and _prepare_transforms.

    Parameters
    ----------
    vcode : str
        Vertex shader code.
    fcode : str
        Fragment shader code.
    gcode : str or None
        Optional geometry shader code.
    program : instance of Program | None
        The program to use. If None, a program will be constructed using
        ``vcode`` and ``fcode``.
    vshare : instance of VisualShare | None
        The visual share, if necessary.
    """

    def __init__(self, vcode='', fcode='', gcode=None, program=None,
                 vshare=None):
        self._view_class = VisualView
        BaseVisual.__init__(self, vshare)
        if vshare is None:
            self._vshare.draw_mode = None
            self._vshare.index_buffer = None
            if program is None:
                self._vshare.program = MultiProgram(vcode, fcode, gcode)
            else:
                self._vshare.program = program
                if len(vcode) > 0 or len(fcode) > 0:
                    raise ValueError("Cannot specify both program and "
                                     "vcode/fcode arguments.")

        self._prev_gl_state = []
        self._program = self._vshare.program.add_program()
        self._prepare_transforms(self)
        self._filters = []
        self._hooks = {}

    def set_gl_state(self, preset=None, **kwargs):
        """Define the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This can also be used as a context manager that will revert the
        gl_state on exit. When used as a context manager, this function is
        designed to be constructed directly in the header of the `with`
        statement to avoid confusion about what state will be restored on exit.

        Parameters
        ----------
        preset : str
            Preset to use.
        **kwargs : dict
            Keyword arguments.
        """
        prev_gl_state = self._vshare.gl_state.copy()

        self._vshare.gl_state = kwargs
        self._vshare.gl_state['preset'] = preset

        return _revert_gl_state([(self, prev_gl_state)])

    def update_gl_state(self, *args, **kwargs):
        """Modify the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This can also be used as a context manager that will revert the
        gl_state on exit.

        Parameters
        ----------
        *args : tuple
            Arguments.
        **kwargs : dict
            Keyword arguments.
        """
        prev_gl_state = self._vshare.gl_state.copy()

        if len(args) == 1:
            self._vshare.gl_state['preset'] = args[0]
        elif len(args) != 0:
            raise TypeError("Only one positional argument allowed.")
        self._vshare.gl_state.update(kwargs)

        return _revert_gl_state([(self, prev_gl_state)])

    def push_gl_state(self, *args, **kwargs):
        """Define the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This differs from :py:meth:`.set_gl_state` in that it stashes the
        current state. See :py:meth:`.pop_gl_state` for restoring the state.

        Parameters
        ----------
        *args : tuple
            Arguments.
        **kwargs : dict
            Keyword arguments.
        """
        self._prev_gl_state.append(self._vshare.gl_state.copy())
        self.set_gl_state(*args, **kwargs)

    def push_gl_state_update(self, *args, **kwargs):
        """Modify the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This differs from :py:meth:`.update_gl_state` in that it stashes the
        current state. See :py:meth:`.pop_gl_state` for restoring the state.

        Parameters
        ----------
        *args : tuple
            Arguments.
        **kwargs : dict
            Keyword arguments.
        """
        self._prev_gl_state.append(self._vshare.gl_state.copy())
        self.update_gl_state(*args, **kwargs)

    def pop_gl_state(self):
        """Restore a previous set of GL state parameters if available.

        If no previous GL state is available (see :py:meth:`.push_gl_state`),
        this has no effect.
        """
        if self._prev_gl_state:
            self.set_gl_state(**self._prev_gl_state.pop())

    def _compute_bounds(self, axis, view):
        """Return the (min, max) bounding values of this visual along *axis*
        in the local coordinate system.
        """
        return None

    def _prepare_draw(self, view=None):
        """This visual is about to be drawn.

        Visuals should implement this method to ensure that all program
        and GL state variables are updated immediately before drawing.

        Return False to indicate that the visual should not be drawn.
        """
        return True

    def _prepare_transforms(self, view):
        """This method is called whenever the TransformSystem instance is
        changed for a view.

        Assign a view's transforms to the proper shader template variables
        on the view's shader program.

        Note that each view has its own TransformSystem. In this method we
        connect the appropriate mapping functions from the view's
        TransformSystem to the view's program.
        """
        raise NotImplementedError()
        # Todo: this method can be removed if we somehow enable the shader
        # to specify exactly which transform functions it needs by name. For
        # example:
        #
        #     // mapping function is automatically defined from the
        #     // corresponding transform in the view's TransformSystem
        #     gl_Position = visual_to_render(a_position);
        #

    @property
    def shared_program(self):
        return self._vshare.program

    @property
    def view_program(self):
        return self._program

    @property
    def _draw_mode(self):
        return self._vshare.draw_mode

    @_draw_mode.setter
    def _draw_mode(self, m):
        self._vshare.draw_mode = m

    @property
    def _index_buffer(self):
        return self._vshare.index_buffer

    @_index_buffer.setter
    def _index_buffer(self, buf):
        self._vshare.index_buffer = buf

    def draw(self):
        if not self.visible:
            return
        if self._prepare_draw(view=self) is False:
            return

        if self._vshare.draw_mode is None:
            raise ValueError("_draw_mode has not been set for visual %r" %
                             self)

        self._configure_gl_state()
        try:
            self._program.draw(self._vshare.draw_mode,
                               self._vshare.index_buffer)
        except Exception:
            logger.warning("Error drawing visual %r" % self)
            raise

    def _configure_gl_state(self):
        gloo.set_state(**self._vshare.gl_state)

    def _get_hook(self, shader, name):
        """Return a FunctionChain that Filters may use to modify the program.

        *shader* should be "vert", "geom", or "frag"
        *name* should be "pre" or "post"
        """
        assert name in ('pre', 'post')
        key = (shader, name)
        if key in self._hooks:
            return self._hooks[key]
        hook = StatementList()
        if shader == 'vert':
            self.view_program.vert[name] = hook
        elif shader == 'frag':
            self.view_program.frag[name] = hook
        elif shader == 'geom':
            self.view_program.geom[name] = hook
        else:
            raise ValueError("shader must be vert, geom, or frag")
        self._hooks[key] = hook
        return hook

    def attach(self, filt, view=None):
        """Attach a Filter to this visual

        Each filter modifies the appearance or behavior of the visual.

        Parameters
        ----------
        filt : object
            The filter to attach.
        view : instance of VisualView | None
            The view to use.
        """
        if view is None:
            self._vshare.filters.append(filt)
            for view in self._vshare.views.keys():
                filt._attach(view)
        else:
            view._filters.append(filt)
            filt._attach(view)

    def detach(self, filt, view=None):
        """Detach a filter.

        Parameters
        ----------
        filt : object
            The filter to detach.
        view : instance of VisualView | None
            The view to use.
        """
        if view is None:
            self._vshare.filters.remove(filt)
            for view in self._vshare.views.keys():
                filt._detach(view)
        else:
            view._filters.remove(filt)
            filt._detach(view)


class VisualView(BaseVisualView, Visual):
    """A view on another Visual instance.

    View instances are created by calling ``visual.view()``.

    Because this is a subclass of `Visual`, all instances of `VisualView`
    define their own shader program (which is a clone of the viewed visual's
    program), transforms, and filter attachments.
    """

    def __init__(self, visual):
        BaseVisualView.__init__(self, visual)
        Visual.__init__(self, vshare=visual._vshare)

        # Attach any shared filters
        for filt in self._vshare.filters:
            filt._attach(self)


class CompoundVisual(BaseVisual):
    """Visual consisting entirely of sub-visuals.

    To the user, a compound visual behaves exactly like a normal visual--it
    has a transform system, draw() and bounds() methods, etc. Internally, the
    compound visual automatically manages proxying these transforms and methods
    to its sub-visuals. 

    Parameters
    ----------
    subvisuals : list of BaseVisual instances
        The list of visuals to be combined in this compound visual.
    """

    def __init__(self, subvisuals):
        self._view_class = CompoundVisualView
        self._subvisuals = []
        BaseVisual.__init__(self)
        for v in subvisuals:
            self.add_subvisual(v)
        self.freeze()

    def add_subvisual(self, visual):
        """Add a subvisual

        Parameters
        ----------
        visual : instance of Visual
            The visual to add.
        """
        visual.transforms = self.transforms
        visual._prepare_transforms(visual)
        self._subvisuals.append(visual)
        visual.events.update.connect(self._subv_update)
        self.update()

    def remove_subvisual(self, visual):
        """Remove a subvisual

        Parameters
        ----------
        visual : instance of Visual
            The visual to remove.
        """
        visual.events.update.disconnect(self._subv_update)
        self._subvisuals.remove(visual)
        self.update()

    def _subv_update(self, event):
        self.update()

    def _transform_changed(self, event=None):
        for v in self._subvisuals:
            v.transforms = self.transforms
        BaseVisual._transform_changed(self)

    def draw(self):
        """Draw the visual"""
        if not self.visible:
            return
        if self._prepare_draw(view=self) is False:
            return

        for v in self._subvisuals:
            if v.visible:
                v.draw()

    def _prepare_draw(self, view):
        pass

    def _prepare_transforms(self, view):
        for v in view._subvisuals:
            v._prepare_transforms(v)

    def set_gl_state(self, preset=None, **kwargs):
        """Define the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This can also be used as a context manager that will revert the
        gl_state on exit.

        Parameters
        ----------
        preset : str
            Preset to use.
        **kwargs : dict
            Keyword arguments.
        """
        prev_gl_state = []
        for v in self._subvisuals:
            prev_gl_state.append((v, v._vshare.gl_state))
            v.set_gl_state(preset=preset, **kwargs)

        return _revert_gl_state(prev_gl_state)

    def update_gl_state(self, *args, **kwargs):
        """Modify the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This can also be used as a context manager that will revert the
        gl_state on exit.

        Parameters
        ----------
        *args : tuple
            Arguments.
        **kwargs : dict
            Keyword arguments.
        """
        prev_gl_state = []
        for v in self._subvisuals:
            prev_gl_state.append((v, v._vshare.gl_state))
            v.update_gl_state(*args, **kwargs)

        return _revert_gl_state(prev_gl_state)

    def push_gl_state(self, *args, **kwargs):
        """Define the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This differs from :py:meth:`.set_gl_state` in that it stashes the
        current state. See :py:meth:`.pop_gl_state` for restoring the state.

        Parameters
        ----------
        *args : tuple
            Arguments.
        **kwargs : dict
            Keyword arguments.
        """
        for v in self._subvisuals:
            v.push_gl_state(*args, **kwargs)

    def push_gl_state_update(self, *args, **kwargs):
        """Modify the set of GL state parameters to use when drawing.

        The arguments are forwarded to :func:`vispy.gloo.wrappers.set_state`.

        This differs from :py:meth:`.update_gl_state` in that it stashes the
        current state. See :py:meth:`.pop_gl_state` for restoring the state.

        Parameters
        ----------
        *args : tuple
            Arguments.
        **kwargs : dict
            Keyword arguments.
        """
        for v in self._subvisuals:
            v.push_gl_state_update(*args, **kwargs)

    def pop_gl_state(self):
        """Restore a previous set of GL state parameters if available.

        If no previous GL state is available (see :py:meth:`.push_gl_state`),
        this has no effect.
        """
        for v in self._subvisuals:
            v.pop_gl_state()

    def attach(self, filt, view=None):
        """Attach a Filter to this visual

        Each filter modifies the appearance or behavior of the visual.

        Parameters
        ----------
        filt : object
            The filter to attach.
        view : instance of VisualView | None
            The view to use.
        """
        for v in self._subvisuals:
            v.attach(filt, v)

    def detach(self, filt, view=None):
        """Detach a filter.

        Parameters
        ----------
        filt : object
            The filter to detach.
        view : instance of VisualView | None
            The view to use.
        """
        for v in self._subvisuals:
            v.detach(filt, v)

    def _compute_bounds(self, axis, view):
        bounds = None
        for v in view._subvisuals:
            if v.visible:
                vb = v.bounds(axis)
                if bounds is None:
                    bounds = vb
                elif vb is not None:
                    bounds = [min(bounds[0], vb[0]), max(bounds[1], vb[1])]
        return bounds


@contextmanager
def _revert_gl_state(prev_gl_state):
    """Context manager to store and revert GL state for a list of visuals.

    Parameters
    ----------
    prev_gl_state : list
        A list of (Visual, gl_state) tuples, where gl_state is a dictionary of
        `gl_state` params as would be passed to :py:func:`set_gl_state`.
    """
    for v, state in prev_gl_state:
        v._prev_gl_state.append(state)
    try:
        yield
    finally:
        for v, _ in prev_gl_state:
            v.pop_gl_state()


class CompoundVisualView(BaseVisualView, CompoundVisual):
    def __init__(self, visual):
        BaseVisualView.__init__(self, visual)
        # Create a view on each sub-visual
        subv = [v.view() for v in visual._subvisuals]
        CompoundVisual.__init__(self, subv)

        # Attach any shared filters
        for filt in self._vshare.filters:
            for v in self._subvisuals:
                filt._attach(v)


class updating_property:
    """A property descriptor that autoupdates the Visual during attribute setting.

    Use this as a decorator in place of the @property when you want the attribute to trigger
    an immediate update to the visual upon change.  You may additionally declare an @setter,
    and if you do, it will be called in addition to the standard logic:
    `self._attr_name = value`.

    For example, the following code examples are equivalent::

        class SomeVisual1(Visual):
            def __init__(self, someprop=None):
                self._someprop = someprop

            @property
            def someprop(self):
                return self._someprop

            @someprop.setter
            def someprop(self, value):
                previous = self._someprop
                if (previous is None) or np.any(value != previous):
                    self._someprop = value
                    self._need_update = True
                    if hasattr(self, 'events'):
                        self.update()

        class SomeVisual2(Visual):
            def __init__(self, someprop=None):
                self._someprop = someprop

            @updating_property
            def someprop(self):
                pass

    NOTE: by default the __get__ method here will look for the conventional `_attr_name`
    property on the object.  The result of this is that you don't actually have to put
    anything in the body of a method decorated with @updating_property if you don't want to
    do anything other than retrieve the property.  So you may see this slightly strange
    pattern being used::

        class SomeVisual2(Visual):
            def __init__(self, someprop=None):
                self._someprop = someprop

            @updating_property
            def someprop(self):
                '''the docstring (or pass) is all that is needed'''

    """

    def __init__(self, fget=None, fset=None, doc=None):
        self.fget = fget
        self.fset = fset
        if self.fget is not None:
            self.attr_name = f'_{self.fget.__name__}'
            self.__doc__ = doc or self.fget.__doc__

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        # if the @updating_property getter returns a value, use that
        val = self.fget(obj)
        if val is not None:
            return val
        # otherwise get the private attribute by the same name
        return getattr(obj, self.attr_name, None)

    def __set__(self, obj, value):
        previous = getattr(obj, self.attr_name, None)
        if (previous is None) or np.any(value != previous):
            setattr(obj, self.attr_name, value)
            # if a @.setter method has been declared, run that as well
            # (overriding the standard setter behavior)
            if self.fset is not None:
                self.fset(obj, value)
            obj._need_update = True
            # prevent update during obj.__init__
            if hasattr(obj, 'events'):
                obj.update()

    def __delete__(self, obj):
        raise AttributeError("can't delete attribute")

    def setter(self, fset):
        return type(self)(self.fget, fset, self.__doc__)
