#pragma region CPL License
/*
Nuclex Native Framework
Copyright (C) 2002-2013 Nuclex Development Labs

This library is free software; you can redistribute it and/or
modify it under the terms of the IBM Common Public License as
published by the IBM Corporation; either version 1.0 of the
License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
IBM Common Public License for more details.

You should have received a copy of the IBM Common Public
License along with this library
*/
#pragma endregion // CPL License

#ifndef NUCLEX_GRAPHICS_RASTERIZATION_RENDERTARGET2_H
#define NUCLEX_GRAPHICS_RASTERIZATION_RENDERTARGET2_H

#include "Texture.h"
#include "../Rectangle.h"
#include "../Color.h"

#include <vector>

namespace Nuclex { namespace Graphics { namespace Rasterization {

  // ------------------------------------------------------------------------------------------- //

  ///<summary>2D texture onto which the rasterizer can draw</summary>
  class RenderTarget2 : public Texture {

    #pragma region class BackingObserver

    /// <summary>Allows the render target to be read from</summary>
    public: class BackingObserver : public Observer {

      /// <summary>Frees the resources used by the backer</summary>
      public: virtual ~BackingObserver() {}

      /// <summary>Reads the specified region of the render target</summary>
      /// <param name="region">Region of the render target that will be read</param>
      /// <param name="target">
      ///   Address at which the render target's pixels will be deposited
      /// </param>
      /// <param name="targetStride">Bytes required to get from one line to the next</param>
      public: virtual void Read(
        const Rectangle &region, void *target, std::size_t targetStride
      ) = 0;

      /// <summary>Resizes the render target to the specified width and height</summary>
      /// <param name="width">New width of the render target</param>
      /// <param name="height">New height of the render target</param>
      public: virtual void Resized(std::size_t width, std::size_t height) = 0;

      /// <summary>Clears the render target to the specified values</summary>
      /// <param name="color">Color the render target will be cleared to</param>
      /// <param name="depth">Depth value the depth buffer will be cleared to</param>
      /// <param name="stencil">Stencil bits the stencil buffer will be cleared to</param>
      public: virtual void Cleared(Color color, float depth, std::uint8_t stencil) = 0;

    };

    #pragma endregion // class BackingObserver

    /// <summary>Initializes a new texture with the specified size</summary>
    /// <param name="width">Width of the texture in pixels</param>
    /// <param name="height">Height of the texture in pixels</param>
    /// <param name="pixelFormat">Memory layout the texture's pixels will use</param>
    /// <param name="usage">How the texture is going to be used</param>
    public: NUCLEX_GRAPHICS_API RenderTarget2(
      std::size_t width, std::size_t height, PixelFormat::Enum pixelFormat,
      Usage::Enum usage = Usage::Immutable
    );

    /// <summary>Initializes a render target by copying an existing render target</summary>
    /// <param name="other">Existing render target that will be copied</param>
    public: NUCLEX_GRAPHICS_API RenderTarget2(const RenderTarget2 &other);

    /// <summary>Destroys the render target</summary>
    public: NUCLEX_GRAPHICS_API virtual ~RenderTarget2();

    /// <summary>Resizes the render target to the specified width and height</summary>
    /// <param name="width">New width of the render target</param>
    /// <param name="height">New height of the render target</param>
    public: NUCLEX_GRAPHICS_API void Resize(std::size_t width, std::size_t height);

    /// <summary>Clears the contents of the render target</summary>
    /// <remarks>
    ///   This will clear the render target to black, with a depth of 1.0 and
    ///   erase all bits in its stencil buffer.
    /// </remarks>
    public: NUCLEX_GRAPHICS_API void Clear() { Clear(Color::Black); }

    /// <summary>Clears the contents of the render target</summary>
    /// <param name="color">Color the render target will be cleared to</param>
    /// <param name="depth">Depth value the depth buffer will be filled with</param>
    /// <param name="stencil">Stencil bits the stencil buffer will be filled with</param>
    public: NUCLEX_GRAPHICS_API void Clear(
      Color color, float depth = 1.0f, std::uint8_t stencil = 0
    );

    /// <summary>Counts the number of dimensions the texture has</summary>
    /// <returns>The texture's number of dimensions</returns>
    public: NUCLEX_GRAPHICS_API virtual std::size_t CountDimensions() const {
      return 2;
    }

    /// <summary>Retrieves the length of one of the texture's dimensions</summary>
    /// <param name="dimensionIndex">
    ///   Index of the dimension whose length will be returned
    /// </param>
    /// <returns>The length of the specified dimension</returns>
    public: NUCLEX_GRAPHICS_API virtual std::size_t GetLength(
      std::size_t dimensionIndex
    ) const;

    /// <summary>Retrieves the width of the texture in pixels</summary>
    /// <returns>The texture's width in pixels</summary>
    public: NUCLEX_GRAPHICS_API std::size_t GetWidth() const { return this->width; }

    /// <summary>Retrieves the height of the texture in pixels</summary>
    /// <returns>The texture's height in pixels</summary>
    public: NUCLEX_GRAPHICS_API std::size_t GetHeight() const { return this->height; }

    /// <summary>Suppresses the notifications and begins queueing them</summary>
    /// <remarks>
    ///   Use this method if you plan to apply many small changes to the buffer in
    ///   order to avoid the overhead that would result in any observers having
    ///   to process hundreds of micro-changes. The buffer will collect all changes
    ///   and merge them. Once notifications are enabled again, a single notification
    ///   even will be fired, containing the changed area.
    /// </remarks>
    public: NUCLEX_GRAPHICS_API void SuppressChangeNotifications();

    /// <summary>Enables change notifications again</summary>
    /// <remarks>
    ///   If any changes happened while notifications were suppressed, this will
    ///   trigger a change notification.
    /// </remarks>
    public: NUCLEX_GRAPHICS_API void PermitChangeNotifications();

    /// <summary>Retrieves the observer attached by the specified owner</summary>
    /// <param name="owner">Owner whose observer will be looked up</param>
    /// <returns>The observer registered by the specified owner or a nullptr</returns>
    public: NUCLEX_GRAPHICS_API BackingObserver *GetObserver(void *owner) const;

    /// <summary>Attaches an observer to the render target</summary>
    /// <param name="owner">The observer's owner, used as a unique key</param>
    /// <param name="observer">Observer that will be attached to the texture</param>
    public: NUCLEX_GRAPHICS_API void AttachObserver(void *owner, BackingObserver *observer);

    /// <summary>Detaches the specified owner's observer from the render target</summary>
    /// <param name="owner">Owner whose observer will be detached</param>
    public: NUCLEX_GRAPHICS_API void DetachObserver(void *owner);

    /// <summary>Copies the contents of another buffer into this buffer</summary>
    /// <param name="other">Other buffer whose contents will be copied</param>
    /// <returns>A reference to this buffer</returns>
    protected: NUCLEX_GRAPHICS_API RenderTarget2 &operator =(const RenderTarget2 &other);

    /// <summary>
    ///   Notifies all observers that the render target is about to be destroyed
    /// </summary>
    protected: NUCLEX_GRAPHICS_API void OnDestroying();

    /// <summary>Notifies all observers that the render target has been resized</summary>
    /// <param name="width">New width of the render target</param>
    /// <param name="height">New height of the render target</param>
    protected: NUCLEX_GRAPHICS_API void OnResized(std::size_t width, std::size_t height);

    /// <summary>Notifies all observers that the render target has been cleared</summary>
    protected: NUCLEX_GRAPHICS_API void OnCleared();

    /// <summary>Notifies all observers that the render target has been cleared</summary>
    /// <param name="color">Color the render target was cleared to</param>
    /// <param name="depth">Depth value the depth buffer was cleared to</param>
    /// <param name="stencil">Stencil bits the stencil buffer was cleared to</param>
    protected: NUCLEX_GRAPHICS_API void OnCleared(
      Color color, float depth, std::uint8_t stencil
    );

    /// <summary>Notifies all observers that the render target has been changed</summary>
    /// <param name="changedRegion">Region that has been changed</param>
    protected: NUCLEX_GRAPHICS_API void OnChanged(const Rectangle &changedRegion);

    /// <summary>Stores the owner and observer attached to the texture</summary>
    private: typedef std::pair<void *, BackingObserver *> AttachedObserver;

    /// <summary>Width of the texture in pixels</summary>
    protected: std::size_t width;
    /// <summary>Height of the texture in pixels</summary>
    protected: std::size_t height;
    /// <summary>Observers to changes happening to the buffer</summary>
    private: std::vector<AttachedObserver> observers;

  };

  // ------------------------------------------------------------------------------------------- //

}}} // namespace Nuclex::Graphics::Rasterization

#endif // NUCLEX_GRAPHICS_RASTERIZATION_RENDERTARGET2_H