From b0a3f08a3011dcf97d5c522eb6c00be83df9eb8d Mon Sep 17 00:00:00 2001 From: mogemimi Date: Thu, 14 Nov 2019 05:14:02 +0900 Subject: [PATCH] Add documentation comments --- include/Pomdog/Graphics/BufferUsage.hpp | 8 ++++++++ include/Pomdog/Graphics/ConstantBuffer.hpp | 6 ++++++ include/Pomdog/Graphics/CullMode.hpp | 6 ++++++ include/Pomdog/Graphics/FillMode.hpp | 4 ++++ include/Pomdog/Graphics/GraphicsDevice.hpp | 3 +++ include/Pomdog/Graphics/IndexBuffer.hpp | 7 +++++++ include/Pomdog/Graphics/IndexElementSize.hpp | 4 ++-- include/Pomdog/Graphics/PrimitiveTopology.hpp | 8 ++++---- include/Pomdog/Graphics/RasterizerDescription.hpp | 12 ++++++++++++ include/Pomdog/Graphics/RenderPass.hpp | 9 +++++++++ include/Pomdog/Graphics/SamplerState.hpp | 1 + include/Pomdog/Graphics/VertexBuffer.hpp | 7 +++++++ include/Pomdog/Graphics/Viewport.hpp | 15 +++++++++++++-- 13 files changed, 82 insertions(+), 8 deletions(-) diff --git a/include/Pomdog/Graphics/BufferUsage.hpp b/include/Pomdog/Graphics/BufferUsage.hpp index 7256aed66..f903ab3bc 100644 --- a/include/Pomdog/Graphics/BufferUsage.hpp +++ b/include/Pomdog/Graphics/BufferUsage.hpp @@ -6,8 +6,16 @@ namespace Pomdog { +/// Identifies the expected usage pattern of graphics buffers during rendering. enum class BufferUsage : std::uint8_t { + /// A resource that can only be read by the GPU. It cannot be accessed by the CPU. + /// + /// A immutable resource must be initialized when it is created, since it cannot be changed after creation. Immutable, + + /// A resource that will be modified repeatedly. It is accessible by both the GPU (read only) and the CPU (write only). + /// + /// A dynamic resource is a good choice for a resource that will be updated by the CPU per frame. Dynamic, }; diff --git a/include/Pomdog/Graphics/ConstantBuffer.hpp b/include/Pomdog/Graphics/ConstantBuffer.hpp index 49b18bf2c..9987056cb 100644 --- a/include/Pomdog/Graphics/ConstantBuffer.hpp +++ b/include/Pomdog/Graphics/ConstantBuffer.hpp @@ -55,6 +55,7 @@ class POMDOG_EXPORT ConstantBuffer final { void GetValue(std::size_t sizeInBytes, void* result) const; + /// Sets constant buffer data. template void SetValue(const T& value) { @@ -62,6 +63,7 @@ class POMDOG_EXPORT ConstantBuffer final { Detail::EffectBinaryParameter::Set(*this, value); } + /// Sets constant buffer data. template void SetValue(const T* data, std::size_t count) { @@ -69,12 +71,16 @@ class POMDOG_EXPORT ConstantBuffer final { Detail::EffectBinaryParameter::Set(*this, data, count); } + /// Sets constant buffer data. void SetValue(const void* data, std::size_t sizeInBytes); + /// Gets the size in bytes of this constant buffer. std::size_t GetSizeInBytes() const noexcept; + /// Gets the expected usage hint of this constant buffer. BufferUsage GetBufferUsage() const noexcept; + /// Gets the pointer of the native constant buffer resource. Detail::NativeBuffer* GetNativeConstantBuffer(); private: diff --git a/include/Pomdog/Graphics/CullMode.hpp b/include/Pomdog/Graphics/CullMode.hpp index e2c3b71cf..36feb56dd 100644 --- a/include/Pomdog/Graphics/CullMode.hpp +++ b/include/Pomdog/Graphics/CullMode.hpp @@ -6,9 +6,15 @@ namespace Pomdog { +/// Indicates whether to cull primitives for hidden surface removal. enum class CullMode : std::uint8_t { + /// Does not cull any back faces. None, + + /// Culls back faces with clockwise vertices. ClockwiseFace, + + /// Culls back faces with counterclockwise vertices. CounterClockwiseFace, }; diff --git a/include/Pomdog/Graphics/FillMode.hpp b/include/Pomdog/Graphics/FillMode.hpp index 3387e54e3..6adcce368 100644 --- a/include/Pomdog/Graphics/FillMode.hpp +++ b/include/Pomdog/Graphics/FillMode.hpp @@ -6,8 +6,12 @@ namespace Pomdog { +/// Determines the fill mode to use when rendering primitives. enum class FillMode : std::uint8_t { + /// Draws polygon edges as line segments. WireFrame, + + /// Rasterizes triangle primitives as filled triangles. Solid, }; diff --git a/include/Pomdog/Graphics/GraphicsDevice.hpp b/include/Pomdog/Graphics/GraphicsDevice.hpp index 92d7f6541..8c5e5cf65 100644 --- a/include/Pomdog/Graphics/GraphicsDevice.hpp +++ b/include/Pomdog/Graphics/GraphicsDevice.hpp @@ -18,10 +18,13 @@ class POMDOG_EXPORT GraphicsDevice final { ~GraphicsDevice(); + /// Gets the currently supported shader language. ShaderLanguage GetSupportedLanguage() const noexcept; + /// Gets the presentation parameters. PresentationParameters GetPresentationParameters() const noexcept; + /// Gets the pointer of the native graphics device. Detail::NativeGraphicsDevice* GetNativeGraphicsDevice(); private: diff --git a/include/Pomdog/Graphics/IndexBuffer.hpp b/include/Pomdog/Graphics/IndexBuffer.hpp index 975f7a87e..da377ba4e 100644 --- a/include/Pomdog/Graphics/IndexBuffer.hpp +++ b/include/Pomdog/Graphics/IndexBuffer.hpp @@ -48,21 +48,28 @@ class POMDOG_EXPORT IndexBuffer final { IndexBuffer& operator=(const IndexBuffer&) = delete; IndexBuffer& operator=(IndexBuffer&&) = default; + /// Gets the number of indices. std::size_t GetIndexCount() const noexcept; + /// Gets the size in bytes of per-index element. IndexElementSize GetElementSize() const noexcept; + /// Gets the size in bytes of this index buffer. std::size_t GetSizeInBytes() const noexcept; + /// Gets the expected usage hint of this index buffer. BufferUsage GetBufferUsage() const noexcept; + /// Sets index buffer data. void SetData(const void* source, std::size_t elementCount); + /// Sets index buffer data. void SetData( std::size_t offsetInBytes, const void* source, std::size_t elementCount); + /// Gets the pointer of the native index buffer resource. Detail::NativeBuffer* GetNativeIndexBuffer(); private: diff --git a/include/Pomdog/Graphics/IndexElementSize.hpp b/include/Pomdog/Graphics/IndexElementSize.hpp index 197f86247..e8f985134 100644 --- a/include/Pomdog/Graphics/IndexElementSize.hpp +++ b/include/Pomdog/Graphics/IndexElementSize.hpp @@ -7,10 +7,10 @@ namespace Pomdog { enum class IndexElementSize : std::uint8_t { - ///@brief 16 bit. + /// A 16-bit unsigned integer used as a the size of a primitive index. SixteenBits, - ///@brief 32 bit. + /// A 32-bit unsigned nteger used as a the size of a primitive index. ThirtyTwoBits, }; diff --git a/include/Pomdog/Graphics/PrimitiveTopology.hpp b/include/Pomdog/Graphics/PrimitiveTopology.hpp index 30db349a7..2f1407cbc 100644 --- a/include/Pomdog/Graphics/PrimitiveTopology.hpp +++ b/include/Pomdog/Graphics/PrimitiveTopology.hpp @@ -7,16 +7,16 @@ namespace Pomdog { enum class PrimitiveTopology : std::uint8_t { - ///@brief A triangle list. + /// A triangle list. TriangleList, - ///@brief A triangle strip. + /// A triangle strip. TriangleStrip, - ///@brief A line list. + /// A line list. LineList, - ///@brief A line strip. + /// A line strip. LineStrip, }; diff --git a/include/Pomdog/Graphics/RasterizerDescription.hpp b/include/Pomdog/Graphics/RasterizerDescription.hpp index c9f1747ca..e55467906 100644 --- a/include/Pomdog/Graphics/RasterizerDescription.hpp +++ b/include/Pomdog/Graphics/RasterizerDescription.hpp @@ -10,10 +10,22 @@ namespace Pomdog { struct POMDOG_EXPORT RasterizerDescription final { + /// A constant depth bias applied to a given pixel. + /// + /// The depth bias (or z-bias) can be added to each of the polygons that + /// are coplanar in 3D space to make them appear as if they are not coplanar. std::int32_t DepthBias; + + /// A scale on a depth gradient of the primitive. float SlopeScaledDepthBias; + + /// Indicates whether to cull primitives for hidden surface removal. Pomdog::CullMode CullMode; + + /// Determines the fill mode to use when rendering primitives. Pomdog::FillMode FillMode; + + /// Enable multisample antialiasing (MSAA). bool MultisampleEnable; static RasterizerDescription CreateDefault() diff --git a/include/Pomdog/Graphics/RenderPass.hpp b/include/Pomdog/Graphics/RenderPass.hpp index 1b861d55a..d2bf47db2 100644 --- a/include/Pomdog/Graphics/RenderPass.hpp +++ b/include/Pomdog/Graphics/RenderPass.hpp @@ -17,10 +17,19 @@ namespace Pomdog { using RenderTargetAndClearColor = std::tuple, std::optional>; struct POMDOG_EXPORT RenderPass final { + /// An array of render targets. std::vector RenderTargets; + + /// A viewport for projection transformations and clipping. std::optional Viewport; + + /// A scissor rectangle for a scissor test. std::optional ScissorRect; + + /// The depth value to use when the depth buffer is cleared. std::optional ClearDepth; + + /// The stencil value to use when the stencil buffer is cleared. std::optional ClearStencil; }; diff --git a/include/Pomdog/Graphics/SamplerState.hpp b/include/Pomdog/Graphics/SamplerState.hpp index 1190a385d..0176d0658 100644 --- a/include/Pomdog/Graphics/SamplerState.hpp +++ b/include/Pomdog/Graphics/SamplerState.hpp @@ -21,6 +21,7 @@ class POMDOG_EXPORT SamplerState final { ~SamplerState(); + /// Gets the pointer of the native sampler state object. Detail::NativeSamplerState* GetNativeSamplerState(); private: diff --git a/include/Pomdog/Graphics/VertexBuffer.hpp b/include/Pomdog/Graphics/VertexBuffer.hpp index abd02b2b3..aa1d4c5ae 100644 --- a/include/Pomdog/Graphics/VertexBuffer.hpp +++ b/include/Pomdog/Graphics/VertexBuffer.hpp @@ -47,22 +47,29 @@ class POMDOG_EXPORT VertexBuffer final { VertexBuffer& operator=(const VertexBuffer&) = delete; VertexBuffer& operator=(VertexBuffer&&) = default; + /// Gets the number of vertices. std::size_t GetVertexCount() const noexcept; + /// Gets the size in bytes of per-vertex data. std::size_t GetStrideBytes() const noexcept; + /// Gets the size in bytes of this vertex buffer. std::size_t GetSizeInBytes() const noexcept; + /// Gets the expected usage hint of this vertex buffer. BufferUsage GetBufferUsage() const noexcept; + /// Sets vertex buffer data. void SetData(const void* source, std::size_t elementCount); + /// Sets vertex buffer data. void SetData( std::size_t offsetInBytes, const void* source, std::size_t elementCount, std::size_t strideInBytes); + /// Gets the pointer of the native vertex buffer resource. Detail::NativeBuffer* GetNativeVertexBuffer(); private: diff --git a/include/Pomdog/Graphics/Viewport.hpp b/include/Pomdog/Graphics/Viewport.hpp index 4ca409bdd..b0751724a 100644 --- a/include/Pomdog/Graphics/Viewport.hpp +++ b/include/Pomdog/Graphics/Viewport.hpp @@ -9,15 +9,22 @@ namespace Pomdog { class POMDOG_EXPORT Viewport final { public: + /// The x coordinate of the upper-left corner of the viewport. int TopLeftX; + + /// The y coordinate of the upper-left corner of the viewport. int TopLeftY; + + /// The width of the viewport, in pixels. int Width; + + /// The height of the viewport, in pixels. int Height; - // The minimum depth of the viewport. It must be between 0.0 and 1.0. + /// The minimum depth of the clip volume. It must be between 0.0 and 1.0. float MinDepth; - // The maximum depth of the viewport. It must be between 0.0 and 1.0. + /// The maximum depth of the clip volume. It must be between 0.0 and 1.0. float MaxDepth; public: @@ -30,16 +37,20 @@ class POMDOG_EXPORT Viewport final { Viewport(int x, int y, int width, int height, float minDepth, float maxDepth) noexcept; + /// Projects a position from object space into screen space. Vector3 Project( const Vector3& source, const Matrix4x4& worldViewProjection) const; + /// Projects a position from screen space into world space. Vector3 Unproject( const Vector3& source, const Matrix4x4& worldViewProjection) const; + /// Gets the boundary of this viewport. [[nodiscard]] Rectangle GetBounds() const noexcept; + /// Gets the aspect ratio used by the viewport, which is width / height. [[nodiscard]] float GetAspectRatio() const noexcept; };