#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_BUFFER_H
#define NUCLEX_GRAPHICS_RASTERIZATION_BUFFER_H

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

#include <cstdint>

namespace Nuclex { namespace Graphics { namespace Rasterization {

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

  ///<summary>Stores sequential data for the vertex shader</summary>
  class Buffer : public Resource {

    #pragma region class Observer

    /// <summary>Receives notifications from the buffer 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 buffer is destroyed</summary>
      public: virtual void Destroying() = 0;

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

      /// <summary>Called when the contents of the buffer have changed</summary>
      /// <param name="offset">
      ///   Offset in the buffer from which on its contents have changed
      /// </param>
      /// <param name="count">Number of bytes that have changed in the buffer</param>
      /// <remarks>
      ///   Offset and count are always specified in bytes.
      /// </remarks>
      public: virtual void Changed(std::size_t offset, std::size_t count) = 0;

    };

    #pragma endregion // class Observer

    /// <summary>Initializes a new buffer with the specified capacity</summary>
    /// <param name="capacityInBytes">Number of bytes to reserve for this buffer</param>
    protected: NUCLEX_GRAPHICS_API Buffer(std::size_t capacityInBytes);

    /// <summary>Creates a copy of an existing buffer</summary>
    /// <param name="other">Existing buffer that will be copied</param>
    /// <remarks>
    ///   The copy will not take over the existing buffer's attached observers.
    /// </remarks>
    protected: NUCLEX_GRAPHICS_API Buffer(const Buffer &other);

    /// <summary>Destroys the buffer</summary>
    public: NUCLEX_GRAPHICS_API virtual ~Buffer();

    /// <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 GetCapacityInBytes() const {
      return this->CapacityBytes;
    }

    /// <summary>Returns the number of bytes used in the buffer</summary>
    /// <returns>The number of bytes the buffer has been filled with</returns>
    public: NUCLEX_GRAPHICS_API std::size_t CountUsedBytes() const {
      return this->usedBytes;
    }

    /// <summary>Resets the buffer to empty</summary>
    public: NUCLEX_GRAPHICS_API void Clear() {
      this->usedBytes = 0;
      OnCleared();
    }

    /// <summary>Accesses the memory used by the buffer</summary>
    /// <returns>The memory storing the buffer contents</returns>
    public: NUCLEX_GRAPHICS_API const std::uint8_t *AccessMemory() const {
      return this->Contents;
    }

    /// <summary>Accesses the memory used by the buffer</summary>
    /// <returns>The memory storing the buffer contents</returns>
    public: NUCLEX_GRAPHICS_API std::uint8_t *AccessMemory() {
      return this->Contents;
    }
/*
    /// <summary>Marks the specified region of the buffer as dirty</summary>
    /// <param name="start">Start offset, in
    public: NUCLEX_GRAPHICS_API void MarkDirty(
      std::size_t start, std::size_t count, bool okayToDiscardOtherContent = false
    );
*/
    /// <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 Observer *GetObserver(const void *owner) const;

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

    /// <summary>Detaches the specified owner's observer from the buffer</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 Buffer &operator =(const Buffer &other);

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

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

    /// <summary>Notifies all observers that the buffer has been changed</summary>
    /// <param name="offset">Offset from which on the buffer has been changed</param>
    /// <param name="count">Number of bytes that have changed in the buffer</param>
    protected: NUCLEX_GRAPHICS_API void OnChanged(
      std::size_t offset, std::size_t count
    );

    /// <summary>The buffer's capacity in bytes</summary>
    protected: const std::size_t CapacityBytes;
    /// <summary>The contents of the buffer</summary>
    /// <remarks>
    ///   The buffer pointer is constant (since a buffer is allocated once and cannot be
    ///   resized or replaced), but the data is not.
    /// </remarks>
    protected: std::uint8_t *const Contents;
    /// <summary>Used buffer space in bytes</summary>
    private: std::size_t usedBytes;
    /// <summary>Index of the first change whilst notifications are suppressed</summary>
    private: std::size_t firstChangeOffset;
    /// <summary>Index one past the last change whilst notifications are suppressed</summary>
    private: std::size_t lastChangeOffset;
    /// <summary>Observers to changes happening to the buffer</summary>
    private: Helpers::ConcurrentObserverSet<Observer> observers;

  };

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

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

#endif // NUCLEX_GRAPHICS_RASTERIZATION_BUFFER_H