#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_TEXTURE2_H
#define NUCLEX_GRAPHICS_RASTERIZATION_TEXTURE2_H

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

namespace Nuclex { namespace Graphics { namespace Rasterization {

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

  ///<summary>Two-dimensional texture typically mapped onto polygons</summary>
  class Texture2 : public Texture {

    /// <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 Texture2(
      std::size_t width, std::size_t height,
      PixelFormat::Enum pixelFormat,
      Usage::Enum usage = Usage::Immutable
    );

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

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

    /// <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();

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

    /// <summary>Write the specified pixels into the texture</summary>
    /// <param name="region">Region of the texture the pixels will be written to</param>
    /// <param name="source">Pixels that will be written into the texture</param>
    /// <param name="sourceStride">Bytes required to get from one line to the next</param>
    public: NUCLEX_GRAPHICS_API void Write(
      const Rectangle &region, const void *source, std::size_t sourceStride
    );

    /// <summary>Accesses the memory used by the texture</summary>
    /// <returns>The memory storing the texture's pixels</returns>
    public: NUCLEX_GRAPHICS_API const std::uint8_t *AccessMemory() const {
      return this->Pixels;
    }

    /// <summary>Accesses the memory used by the texture</summary>
    /// <returns>The memory storing the texture's pixels</returns>
    public: NUCLEX_GRAPHICS_API std::uint8_t *AccessMemory() {
      return this->Pixels;
    }

    /// <summary>Marks the specified region of the texture as dirty</summary>
    /// <param name="region">Region that will be marked as dirty</param>
    public: NUCLEX_GRAPHICS_API void MarkDirty(const Rectangle &region);

    /// <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>
    public: NUCLEX_GRAPHICS_API Texture2 &operator =(const Texture2 &other);

    /// <summary>Verifies that the region to be read or written is in order</summary>
    /// <param name="region">Region that will be verified</param>
    /// <remarks>
    ///   Regions must not leave the texture and compressed pixel formats may
    ///   require them to be aligned to compressed blocks (for example, in BC3 each
    ///   16 bytes describe a 4x4 pixel region, so the region coordinates need to be
    ///   a multiple of 4 on both axes).
    /// </remarks>
    private: void verifyRegion(const Rectangle &region) const;

    /// <summary>Width of the texture in pixels</summary>
    protected: const std::size_t width;
    /// <summary>Height of the texture in pixels</summary>
    protected: const std::size_t height;

  };

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

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

#endif // NUCLEX_GRAPHICS_RASTERIZATION_TEXTURE2_H