palQueryPool.h

/*
 ***********************************************************************************************************************
 *
 *  Copyright (c) 2014-2024 Advanced Micro Devices, Inc. All Rights Reserved.
 *
 *  Permission is hereby granted, free of charge, to any person obtaining a copy
 *  of this software and associated documentation files (the "Software"), to deal
 *  in the Software without restriction, including without limitation the rights
 *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 *  copies of the Software, and to permit persons to whom the Software is
 *  furnished to do so, subject to the following conditions:
 *
 *  The above copyright notice and this permission notice shall be included in all
 *  copies or substantial portions of the Software.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 *  SOFTWARE.
 *
 **********************************************************************************************************************/
/**
 ***********************************************************************************************************************
 * @file  palQueryPool.h
 * @brief Defines the Platform Abstraction Library (PAL) IQueryPool interface and related types.
 ***********************************************************************************************************************
 */

#pragma once

#include "pal.h"
#include "palGpuMemoryBindable.h"

namespace Pal
{

/// Specifies a category of GPU query pool.
enum class QueryPoolType : uint32
{
    Occlusion        = 0x0,  ///< Occlusion query pool. Supports queries based on the Z test.
    PipelineStats    = 0x1,  ///< Pipeline stats query pool. Supports queries based on statistics from the GPU's execution
                             ///  such as a count of prims generated, shader invocations, etc.
    StreamoutStats   = 0x2,  ///< Streamout query pool. Supports queries based on statistics from the GPU's execution
                             ///  such as number of primitives written to SO buffer and storage needed.
    Count,
};

/// Specifies what data a query slot must produce. Some query pool types support multiple query types.
enum class QueryType : uint32
{
    Occlusion        = 0x0, ///< The total passes recorded by the Z test.
    BinaryOcclusion  = 0x1, ///< One if there were one or more Z test passes, zero otherwise.
    PipelineStats    = 0x2, ///< The total statistics selected by the given pipeline stats query pool.
    StreamoutStats   = 0x3, ///< SO statistics tracked by CP/VGT including primitives written and storage needed.
    StreamoutStats1  = 0x4, ///< SO1 statistics tracked by CP/VGT including primitives written and storage needed.
    StreamoutStats2  = 0x5, ///< SO2 statistics tracked by CP/VGT including primitives written and storage needed.
    StreamoutStats3  = 0x6, ///< SO3 statistics tracked by CP/VGT including primitives written and storage needed.
    Count,
};

/// Specifies which pipeline stats should be tracked by a pipeline stats query pool.
enum QueryPipelineStatsFlags : uint32
{
    QueryPipelineStatsIaVertices    = 0x1,    ///< Input vertices.
    QueryPipelineStatsIaPrimitives  = 0x2,    ///< Input primitives.
    QueryPipelineStatsVsInvocations = 0x4,    ///< Vertex shader invocations.
    QueryPipelineStatsGsInvocations = 0x8,    ///< Geometry shader invocations.
    QueryPipelineStatsGsPrimitives  = 0x10,   ///< Geometry shader primitives.
    QueryPipelineStatsCInvocations  = 0x20,   ///< Clipper invocations.
    QueryPipelineStatsCPrimitives   = 0x40,   ///< Clipper primitives.
    QueryPipelineStatsPsInvocations = 0x80,   ///< Pixel shader invocations.
    QueryPipelineStatsHsInvocations = 0x100,  ///< Hull shader invocations.
    QueryPipelineStatsDsInvocations = 0x200,  ///< Domain shader invocations.
    QueryPipelineStatsCsInvocations = 0x400,  ///< Compute shader invocations.
    QueryPipelineStatsTsInvocations = 0x800,  ///< Task shader invocations.
    QueryPipelineStatsMsInvocations = 0x1000, ///< Mesh shader invocations.
    QueryPipelineStatsMsPrimitives  = 0x2000, ///< Mesh shader primitives.
    QueryPipelineStatsAll           = 0x3FFF  ///< All of the above stats.
};

/// Specifies properties for @ref IQueryPool creation.  Input structure to IDevice::CreateQueryPool().
struct QueryPoolCreateInfo
{
    QueryPoolType queryPoolType;    ///< Type of query pool to create (i.e., occlusion vs. pipeline stats).
    uint32        numSlots;         ///< Number of slots in the query pool.
    uint32        enabledStats;     ///< An ORed mask of stats flags specific to the query pool type.
                                    ///  @see QueryPipelineStatsFlags for PipelineStats query pools.
    union
    {
        struct
        {
            /// If true, this query pool can have results retrieved using the CPU (using @ref IQueryPool::GetResults)
            /// and can be reset using the CPU (using @ref IQueryPool::Reset).  Otherwise, the client must use command
            /// buffers to perform these operations (using @ref ICmdBuffer::CmdResetQueryPool and
            /// @ref ICmdBuffer::CmdResolveQuery).
            uint32  enableCpuAccess :  1;
            uint32  reserved        : 31;   ///< Reserved for future use.
        };
        uint32  u32All; ///< Flags packed together as a uint32.
    } flags;            ///< Flags controlling QueryPool behavior.
};

/// Controls operations that compute query results.
enum QueryResultFlags : uint32
{
    QueryResultDefault          =  0x0, ///< Default to 32-bit results with no waiting.
    QueryResult64Bit            =  0x1, ///< Store all results as 64-bit values.
    QueryResultWait             =  0x2, ///< Wait for the queries to finish when computing the results.
    QueryResultAvailability     =  0x4, ///< If the results of a query are available at computation time a one will be
                                        ///  written as a separate value after the result value, if the results were not
                                        ///  available a zero will be written.
    QueryResultPartial          =  0x8, ///< If the final result of a query would be unavailable, then return a
                                        ///  result for that query between 0 and what the final result would be.
    QueryResultAccumulate       = 0x10, ///< Results are added to the values present in the destination, if availability
                                        ///  data is enabled it will be ANDed with the present availability data.
    QueryResultPreferShaderPath = 0x20, ///< Prefer a shader resolve path over a command processor path.
    QueryResultOnlyPrimNeeded   = 0x40, ///< Select only primitives storage needed in Streamout query results
    QueryResultAll              = 0x7F  ///< Clients should NOT use it, for internal static_assert purpose only.
};

/**
 ***********************************************************************************************************************
 * @interface IQueryPool
 * @brief     Represents a set of queries that can be used to retrieve detailed info about the GPU's execution of a
 *            particular range of a command buffer.
 *
 * Currently, only occlusion queries and pipeline statistic queries are supported.  All queries in a pool are the same
 * type.
 *
 * @see IDevice::CreateQueryPool()
 ***********************************************************************************************************************
 */
class IQueryPool : public IGpuMemoryBindable
{
public:
    /// Retrieves query results from a query pool.
    ///
    /// Multiple consecutive query results can be retrieved with one call.
    ///
    /// @param [in]     flags      Flags that control the result data layout and how the results are retrieved.
    /// @param [in]     queryType  Specifies what data the query slots must produce.
    /// @param [in]     startQuery First query pool slot to retrieve data for.
    /// @param [in]     queryCount Number of query pool slots to retrieve data for.
    /// @param [in]     pMappedGpuAddr Specify the query buffer mapped address. If the parameter equals nullptr,
    //                                 this method will use Map\UnMap to access the data.
    /// @param [in,out] pDataSize  Input value specifies the available size in pData in bytes; output value reports the
    ///                            number of bytes required to hold all result data.
    /// @param [out]    pData      Location where the query results should be written. Can be null in order to query the
    ///                            required size. The data returned depends on the query pool type and flags. All data
    ///                            entries are either uint32 or uint64 integers. One or more type-specific entries will
    ///                            be optionally followed by one entry for availability. The type-specific data is:<br>
    ///                            + QueryOcclusion: One entry to store the zPass count.
    ///                            + QueryPipelineStats: One entry per statistic enabled in the create info. The stats
    ///                              will be written in the appropriate order for each PAL client.
    /// @param [in]     stride     Stride in bytes between subsequent query result data or zero to request tightly
    ///                            packed result data.
    ///
    /// @returns Success if query results were successfully returned in pData, or NotReady if any of the requested query
    ///          slots does not yet have results available.  Otherwise, one of the following error codes may be
    ///          returned:
    ///          + ErrorInvalidValue if the range defined by startQuery and queryCount is not valid for this query pool.
    ///          + ErrorGpuMemoryNotBound if the query pool requires GPU memory but none is bound.
    ///          + ErrorInvalidMemorySize if pData is non-null and the value stored in pDataSize is too small.
    virtual Result GetResults(
        QueryResultFlags flags,
        QueryType        queryType,
        uint32           startQuery,
        uint32           queryCount,
        const void*      pMappedGpuAddr,
        size_t*          pDataSize,
        void*            pData,
        size_t           stride) = 0;

    /// Use CPU to reset the query pool slots.
    ///
    /// Supported for occlusion and video decode statistics query pools.
    ///
    /// @param [in]     startQuery     First query pool slot to reset.
    /// @param [in]     queryCount     Number of query pool slots to reset.
    /// @param [in]     pMappedCpuAddr Specify the query buffer mapped address. If the parameter equals nullptr,
    //                                 this method will use Map/UnMap to access the data.
    ///
    /// @returns Success if the reset was successfully performed.
    virtual Result Reset(
        uint32  startQuery,
        uint32  queryCount,
        void*   pMappedCpuAddr) = 0;

    /// Returns the value of the associated arbitrary client data pointer.
    /// Can be used to associate arbitrary data with a particular PAL object.
    ///
    /// @returns Pointer to client data.
    void* GetClientData() const
    {
        return m_pClientData;
    }

    /// Sets the value of the associated arbitrary client data pointer.
    /// Can be used to associate arbitrary data with a particular PAL object.
    ///
    /// @param  [in]    pClientData     A pointer to arbitrary client data.
    void SetClientData(
        void* pClientData)
    {
        m_pClientData = pClientData;
    }

protected:
    /// @internal Constructor. Prevent use of new operator on this interface. Client must create objects by explicitly
    /// called the proper create method.
    IQueryPool() : m_pClientData(nullptr) {}

    /// @internal Destructor.  Prevent use of delete operator on this interface.  Client must destroy objects by
    /// explicitly calling IDestroyable::Destroy() and is responsible for freeing the system memory allocated for the
    /// object on their own.
    virtual ~IQueryPool() { }

private:
    /// @internal Client data pointer. This can have an arbitrary value and can be returned by calling GetClientData()
    /// and set via SetClientData().
    /// For non-top-layer objects, this will point to the layer above the current object.
    void* m_pClientData;
};

} // Pal