#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_TEXTURE_H
#define NUCLEX_GRAPHICS_RASTERIZATION_TEXTURE_H

#include "Resource.h"
#include "PixelFormat.h"
#include "Usage.h"
#include "../Box.h"
#include "../Helpers/ConcurrentObserverSet.h"

#include <cstdint>

namespace Nuclex { namespace Graphics { namespace Rasterization {

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

  ///<summary>Multi-dimensional data used for image sampling and lookup tables</summary>
  class Texture : public Resource {

    #pragma region class Observer

    /// <summary>Receives notifications from the texture when it changes</summary>
    public: class Observer : public Resource::Observer {

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

      /// <summary>Called right before the texture is destroyed</summary>
      public: virtual void Destroying() = 0;

      /// <summary>Called when the texture has been cleared</summary>
      public: virtual void Cleared() = 0;

      /// <summary>Called when the texture has been modified</summary>
      /// <param name="changedBox">Box around the changed area</param>
      /// <remarks>
      ///   This callback is used for textures of any dimensionality (well, up to 3
      ///   naturally). The unused coordinates will be set to 0 and 1 for consistency,
      ///   so a 2D texture, for example, will generate boxes with the
      ///   <see cref="Box.Back" /> coordinate set to 0 and <see cref="Box.Front" />
      ///   coordinate set to 1.
      /// </remarks>
      public: virtual void Changed(const Box &changedBox) = 0;

    };

    #pragma endregion // class Observer

    /// <summary>Initializes a new texture with the specified size</summary>
    /// <param name="sizeInBytes">Space required to store the texture in bytes</param>
    /// <param name="pixelFormat">Memory layout the texture's pixels will use</param>
    /// <param name="usage">How the texture will be accessed</param>
    public: NUCLEX_GRAPHICS_API Texture(
      std::size_t sizeInBytes, PixelFormat::Enum pixelFormat, Usage::Enum usage
    );

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

    /// <summary>Destroys the texture</summary>
    public: NUCLEX_GRAPHICS_API virtual ~Texture();

    /// <summary>Returns the capacity of the buffer in bytes</summary>
    /// <returns>The number of  bytes that fit in the buffer</returns>
    public: NUCLEX_GRAPHICS_API std::size_t GetSizeInBytes() const {
      return this->SizeInBytes;
    }

    /// <summary>Erases the contents of the texture</summary>
    public: NUCLEX_GRAPHICS_API virtual void Clear() = 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 = 0;

    /// <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 = 0;

    /// <summary>Returns the pixel format used by the texture</summary>
    /// <returns>The pixel format the texture uses</returns>
    public: NUCLEX_GRAPHICS_API PixelFormat::Enum GetPixelFormat() const {
      return this->PixelFormat;
    }

    /// <summary>Returns the indicates usage of the texture</summary>
    /// <returns>How the texture will be accessed by the CPU and the GPU</returns>
    public: NUCLEX_GRAPHICS_API Usage::Enum GetUsage() const {
      return this->usage;
    }

    /// <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 virtual 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 virtual 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 Observer *GetObserver(const void *owner) const;

    /// <summary>Attaches an observer to the texture</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(const void *owner, Observer *observer);

    /// <summary>Detaches the specified owner's observer from the texture</summary>
    /// <param name="owner">Owner whose observer will be detached</param>
    public: NUCLEX_GRAPHICS_API void DetachObserver(const 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 Texture &operator =(const Texture &other);

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

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

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

    /// <summary>Pixel format used by the texture</summary>
    protected: const PixelFormat::Enum PixelFormat;
    /// <summary>Size of the texture in bytes</summary>
    protected: const std::size_t SizeInBytes;
    /// <summary>The contents of the buffer</summary>
    /// <remarks>
    ///   The pixel pointer is constant (since a texture is allocated once and cannot be
    ///   resized or replaced), but the data is not.
    /// </remarks>
    protected: std::uint8_t *const Pixels;
    /// <summary>How the texture will be accessed by the CPU and the GPU</summary>
    private: Usage::Enum usage;
    /// <summary>Region that has changed whilst notifications were suppressed</summary>
    private: Box changedRegion;
    /// <summary>Observers to changes happening to the buffer</summary>
    private: Helpers::ConcurrentObserverSet<Observer> observers;

  };

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

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

#endif // NUCLEX_GRAPHICS_RASTERIZATION_TEXTURE_H