src/gallium/drivers/swr/rasterizer/core/api.h

   1 /****************************************************************************
   2 * Copyright (C) 2014-2015 Intel Corporation.   All Rights Reserved.
   3 *
   4 * Permission is hereby granted, free of charge, to any person obtaining a
   5 * copy of this software and associated documentation files (the "Software"),
   6 * to deal in the Software without restriction, including without limitation
   7 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
   8 * and/or sell copies of the Software, and to permit persons to whom the
   9 * Software is furnished to do so, subject to the following conditions:
  10 *
  11 * The above copyright notice and this permission notice (including the next
  12 * paragraph) shall be included in all copies or substantial portions of the
  13 * Software.
  14 *
  15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  18 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  21 * IN THE SOFTWARE.
  22 *
  23 * @file api.h
  24 *
  25 * @brief API definitions
  26 *
  27 ******************************************************************************/
  28
  29 #ifndef __SWR_API_H__
  30 #define __SWR_API_H__
  31
  32 #include "common/os.h"
  33
  34 #include <assert.h>
  35 #include <vector>
  36
  37 #include "common/simdintrin.h"
  38 #include "common/formats.h"
  39 #include "core/utils.h"
  40 #include "core/state.h"
  41
  42 ///@todo place all the API functions into the 'swr' namespace.
  43
  44 typedef void(SWR_API *PFN_CALLBACK_FUNC)(uint64_t data, uint64_t data2, uint64_t data3);
  45
  46 //////////////////////////////////////////////////////////////////////////
  47 /// @brief Function signature for load hot tiles
  48 /// @param hPrivateContext - handle to private data
  49 /// @param dstFormat - format of the hot tile
  50 /// @param renderTargetIndex - render target to store, can be color, depth or stencil
  51 /// @param x - destination x coordinate
  52 /// @param y - destination y coordinate
  53 /// @param pDstHotTile - pointer to the hot tile surface
  54 typedef void(SWR_API *PFN_LOAD_TILE)(HANDLE hPrivateContext, SWR_FORMAT dstFormat,
  55     SWR_RENDERTARGET_ATTACHMENT renderTargetIndex,
  56     uint32_t x, uint32_t y, uint32_t renderTargetArrayIndex, uint8_t *pDstHotTile);
  57
  58 //////////////////////////////////////////////////////////////////////////
  59 /// @brief Function signature for store hot tiles
  60 /// @param hPrivateContext - handle to private data
  61 /// @param srcFormat - format of the hot tile
  62 /// @param renderTargetIndex - render target to store, can be color, depth or stencil
  63 /// @param x - destination x coordinate
  64 /// @param y - destination y coordinate
  65 /// @param pSrcHotTile - pointer to the hot tile surface
  66 typedef void(SWR_API *PFN_STORE_TILE)(HANDLE hPrivateContext, SWR_FORMAT srcFormat,
  67     SWR_RENDERTARGET_ATTACHMENT renderTargetIndex,
  68     uint32_t x, uint32_t y, uint32_t renderTargetArrayIndex, uint8_t *pSrcHotTile);
  69
  70 /// @brief Function signature for clearing from the hot tiles clear value
  71 /// @param hPrivateContext - handle to private data
  72 /// @param renderTargetIndex - render target to store, can be color, depth or stencil
  73 /// @param x - destination x coordinate
  74 /// @param y - destination y coordinate
  75 /// @param pClearColor - pointer to the hot tile's clear value
  76 typedef void(SWR_API *PFN_CLEAR_TILE)(HANDLE hPrivateContext,
  77     SWR_RENDERTARGET_ATTACHMENT rtIndex,
  78     uint32_t x, uint32_t y, const float* pClearColor);
  79
  80 class BucketManager;
  81
  82 //////////////////////////////////////////////////////////////////////////
  83 /// SWR_CREATECONTEXT_INFO
  84 /////////////////////////////////////////////////////////////////////////
  85 struct SWR_CREATECONTEXT_INFO
  86 {
  87     DRIVER_TYPE driver;
  88
  89     // External functions (e.g. sampler) need per draw context state.
  90     // Use SwrGetPrivateContextState() to access private state.
  91     uint32_t privateStateSize;
  92
  93     // Tile manipulation functions
  94     PFN_LOAD_TILE pfnLoadTile;
  95     PFN_STORE_TILE pfnStoreTile;
  96     PFN_CLEAR_TILE pfnClearTile;
  97
  98     // Pointer to rdtsc buckets mgr returned to the caller.
  99     // Only populated when KNOB_ENABLE_RDTSC is set
 100     BucketManager* pBucketMgr;
 101
 102     // Output: size required memory passed to for SwrSaveState / SwrRestoreState
 103     size_t  contextSaveSize;
 104 };
 105
 106 //////////////////////////////////////////////////////////////////////////
 107 /// SWR_RECT
 108 /////////////////////////////////////////////////////////////////////////
 109 struct SWR_RECT
 110 {
 111     uint32_t left;
 112     uint32_t right;
 113     uint32_t top;
 114     uint32_t bottom;
 115 };
 116
 117 //////////////////////////////////////////////////////////////////////////
 118 /// @brief Create SWR Context.
 119 /// @param pCreateInfo - pointer to creation info.
 120 HANDLE SWR_API SwrCreateContext(
 121     SWR_CREATECONTEXT_INFO* pCreateInfo);
 122
 123 //////////////////////////////////////////////////////////////////////////
 124 /// @brief Destroys SWR Context.
 125 /// @param hContext - Handle passed back from SwrCreateContext
 126 void SWR_API SwrDestroyContext(
 127     HANDLE hContext);
 128
 129 //////////////////////////////////////////////////////////////////////////
 130 /// @brief Saves API state associated with hContext
 131 /// @param hContext - Handle passed back from SwrCreateContext
 132 /// @param pOutputStateBlock - Memory block to receive API state data
 133 /// @param memSize - Size of memory pointed to by pOutputStateBlock
 134 void SWR_API SwrSaveState(
 135     HANDLE hContext,
 136     void* pOutputStateBlock,
 137     size_t memSize);
 138
 139 //////////////////////////////////////////////////////////////////////////
 140 /// @brief Restores API state to hContext previously saved with SwrSaveState
 141 /// @param hContext - Handle passed back from SwrCreateContext
 142 /// @param pStateBlock - Memory block to read API state data from
 143 /// @param memSize - Size of memory pointed to by pStateBlock
 144 void SWR_API SwrRestoreState(
 145     HANDLE hContext,
 146     const void* pStateBlock,
 147     size_t memSize);
 148
 149 //////////////////////////////////////////////////////////////////////////
 150 /// @brief Sync cmd. Executes the callback func when all rendering up to this sync
 151 ///        has been completed
 152 /// @param hContext - Handle passed back from SwrCreateContext
 153 /// @param pfnFunc - pointer to callback function,
 154 /// @param userData - user data to pass back
 155 void SWR_API SwrSync(
 156     HANDLE hContext,
 157     PFN_CALLBACK_FUNC pfnFunc,
 158     uint64_t userData,
 159     uint64_t userData2,
 160     uint64_t userData3 = 0);
 161
 162 //////////////////////////////////////////////////////////////////////////
 163 /// @brief Blocks until all rendering has been completed.
 164 /// @param hContext - Handle passed back from SwrCreateContext
 165 void SWR_API SwrWaitForIdle(
 166     HANDLE hContext);
 167
 168 //////////////////////////////////////////////////////////////////////////
 169 /// @brief Set vertex buffer state.
 170 /// @param hContext - Handle passed back from SwrCreateContext
 171 /// @param numBuffers - Number of vertex buffer state descriptors.
 172 /// @param pVertexBuffers - Array of vertex buffer state descriptors.
 173 void SWR_API SwrSetVertexBuffers(
 174     HANDLE hContext,
 175     uint32_t numBuffers,
 176     const SWR_VERTEX_BUFFER_STATE* pVertexBuffers);
 177
 178 //////////////////////////////////////////////////////////////////////////
 179 /// @brief Set index buffer
 180 /// @param hContext - Handle passed back from SwrCreateContext
 181 /// @param pIndexBuffer - Index buffer.
 182 void SWR_API SwrSetIndexBuffer(
 183     HANDLE hContext,
 184     const SWR_INDEX_BUFFER_STATE* pIndexBuffer);
 185
 186 //////////////////////////////////////////////////////////////////////////
 187 /// @brief Set fetch shader pointer.
 188 /// @param hContext - Handle passed back from SwrCreateContext
 189 /// @param pfnFetchFunc - Pointer to shader.
 190 void SWR_API SwrSetFetchFunc(
 191     HANDLE hContext,
 192     PFN_FETCH_FUNC    pfnFetchFunc);
 193
 194 //////////////////////////////////////////////////////////////////////////
 195 /// @brief Set streamout shader pointer.
 196 /// @param hContext - Handle passed back from SwrCreateContext
 197 /// @param pfnSoFunc - Pointer to shader.
 198 /// @param streamIndex - specifies stream
 199 void SWR_API SwrSetSoFunc(
 200     HANDLE hContext,
 201     PFN_SO_FUNC    pfnSoFunc,
 202     uint32_t streamIndex);
 203
 204 //////////////////////////////////////////////////////////////////////////
 205 /// @brief Set streamout state
 206 /// @param hContext - Handle passed back from SwrCreateContext
 207 /// @param pSoState - Pointer to streamout state.
 208 void SWR_API SwrSetSoState(
 209     HANDLE hContext,
 210     SWR_STREAMOUT_STATE* pSoState);
 211
 212 //////////////////////////////////////////////////////////////////////////
 213 /// @brief Set streamout buffer state
 214 /// @param hContext - Handle passed back from SwrCreateContext
 215 /// @param pSoBuffer - Pointer to streamout buffer.
 216 /// @param slot - Slot to bind SO buffer to.
 217 void SWR_API SwrSetSoBuffers(
 218     HANDLE hContext,
 219     SWR_STREAMOUT_BUFFER* pSoBuffer,
 220     uint32_t slot);
 221
 222 //////////////////////////////////////////////////////////////////////////
 223 /// @brief Set vertex shader pointer.
 224 /// @param hContext - Handle passed back from SwrCreateContext
 225 /// @param pfnVertexFunc - Pointer to shader.
 226 void SWR_API SwrSetVertexFunc(
 227     HANDLE hContext,
 228     PFN_VERTEX_FUNC pfnVertexFunc);
 229
 230 //////////////////////////////////////////////////////////////////////////
 231 /// @brief Set frontend state.
 232 /// @param hContext - Handle passed back from SwrCreateContext
 233 /// @param pState - Pointer to state
 234 void SWR_API SwrSetFrontendState(
 235     HANDLE hContext,
 236     SWR_FRONTEND_STATE *pState);
 237
 238 //////////////////////////////////////////////////////////////////////////
 239 /// @brief Set geometry shader state.
 240 /// @param hContext - Handle passed back from SwrCreateContext
 241 /// @param pState - Pointer to state
 242 void SWR_API SwrSetGsState(
 243     HANDLE hContext,
 244     SWR_GS_STATE *pState);
 245
 246 //////////////////////////////////////////////////////////////////////////
 247 /// @brief Set geometry shader
 248 /// @param hContext - Handle passed back from SwrCreateContext
 249 /// @param pState - Pointer to geometry shader function
 250 void SWR_API SwrSetGsFunc(
 251     HANDLE hContext,
 252     PFN_GS_FUNC pfnGsFunc);
 253
 254 //////////////////////////////////////////////////////////////////////////
 255 /// @brief Set compute shader
 256 /// @param hContext - Handle passed back from SwrCreateContext
 257 /// @param pfnCsFunc - Pointer to compute shader function
 258 /// @param totalThreadsInGroup - product of thread group dimensions.
 259 /// @param totalSpillFillSize - size in bytes needed for spill/fill.
 260 void SWR_API SwrSetCsFunc(
 261     HANDLE hContext,
 262     PFN_CS_FUNC pfnCsFunc,
 263     uint32_t totalThreadsInGroup,
 264     uint32_t totalSpillFillSize);
 265
 266 //////////////////////////////////////////////////////////////////////////
 267 /// @brief Set tessellation state.
 268 /// @param hContext - Handle passed back from SwrCreateContext
 269 /// @param pState - Pointer to state
 270 void SWR_API SwrSetTsState(
 271     HANDLE hContext,
 272     SWR_TS_STATE *pState);
 273
 274 //////////////////////////////////////////////////////////////////////////
 275 /// @brief Set hull shader
 276 /// @param hContext - Handle passed back from SwrCreateContext
 277 /// @param pfnFunc - Pointer to shader function
 278 void SWR_API SwrSetHsFunc(
 279     HANDLE hContext,
 280     PFN_HS_FUNC pfnFunc);
 281
 282 //////////////////////////////////////////////////////////////////////////
 283 /// @brief Set domain shader
 284 /// @param hContext - Handle passed back from SwrCreateContext
 285 /// @param pfnFunc - Pointer to shader function
 286 void SWR_API SwrSetDsFunc(
 287     HANDLE hContext,
 288     PFN_DS_FUNC pfnFunc);
 289
 290 //////////////////////////////////////////////////////////////////////////
 291 /// @brief Set depth stencil state
 292 /// @param hContext - Handle passed back from SwrCreateContext
 293 /// @param pState - Pointer to state.
 294 void SWR_API SwrSetDepthStencilState(
 295     HANDLE hContext,
 296     SWR_DEPTH_STENCIL_STATE *pState);
 297
 298 //////////////////////////////////////////////////////////////////////////
 299 /// @brief Set backend state
 300 /// @param hContext - Handle passed back from SwrCreateContext
 301 /// @param pState - Pointer to state.
 302 void SWR_API SwrSetBackendState(
 303     HANDLE hContext,
 304     SWR_BACKEND_STATE *pState);
 305
 306 //////////////////////////////////////////////////////////////////////////
 307 /// @brief Set pixel shader state
 308 /// @param hContext - Handle passed back from SwrCreateContext
 309 /// @param pState - Pointer to state.
 310 void SWR_API SwrSetPixelShaderState(
 311     HANDLE hContext,
 312     SWR_PS_STATE *pState);
 313
 314 //////////////////////////////////////////////////////////////////////////
 315 /// @brief Set blend state
 316 /// @param hContext - Handle passed back from SwrCreateContext
 317 /// @param pState - Pointer to state.
 318 void SWR_API SwrSetBlendState(
 319     HANDLE hContext,
 320     SWR_BLEND_STATE *pState);
 321
 322 //////////////////////////////////////////////////////////////////////////
 323 /// @brief Set blend function
 324 /// @param hContext - Handle passed back from SwrCreateContext
 325 /// @param renderTarget - render target index
 326 /// @param pfnBlendFunc - function pointer
 327 void SWR_API SwrSetBlendFunc(
 328     HANDLE hContext,
 329     uint32_t renderTarget,
 330     PFN_BLEND_JIT_FUNC pfnBlendFunc);
 331
 332 //////////////////////////////////////////////////////////////////////////
 333 /// @brief SwrDraw
 334 /// @param hContext - Handle passed back from SwrCreateContext
 335 /// @param topology - Specifies topology for draw.
 336 /// @param startVertex - Specifies start vertex in vertex buffer for draw.
 337 /// @param primCount - Number of vertices.
 338 void SWR_API SwrDraw(
 339     HANDLE hContext,
 340     PRIMITIVE_TOPOLOGY topology,
 341     uint32_t startVertex,
 342     uint32_t primCount);
 343
 344 //////////////////////////////////////////////////////////////////////////
 345 /// @brief SwrDrawInstanced
 346 /// @param hContext - Handle passed back from SwrCreateContext
 347 /// @param topology - Specifies topology for draw.
 348 /// @param numVertsPerInstance - How many vertices to read sequentially from vertex data.
 349 /// @param numInstances - How many instances to render.
 350 /// @param startVertex - Specifies start vertex for draw. (vertex data)
 351 /// @param startInstance - Which instance to start sequentially fetching from in each buffer (instanced data)
 352 void SWR_API SwrDrawInstanced(
 353     HANDLE hContext,
 354     PRIMITIVE_TOPOLOGY topology,
 355     uint32_t numVertsPerInstance,
 356     uint32_t numInstances,
 357     uint32_t startVertex,
 358     uint32_t startInstance);
 359
 360 //////////////////////////////////////////////////////////////////////////
 361 /// @brief DrawIndexed
 362 /// @param hContext - Handle passed back from SwrCreateContext
 363 /// @param topology - Specifies topology for draw.
 364 /// @param numIndices - Number of indices to read sequentially from index buffer.
 365 /// @param indexOffset - Starting index into index buffer.
 366 /// @param baseVertex - Vertex in vertex buffer to consider as index "0". Note value is signed.
 367 void SWR_API SwrDrawIndexed(
 368     HANDLE hContext,
 369     PRIMITIVE_TOPOLOGY topology,
 370     uint32_t numIndices,
 371     uint32_t indexOffset,
 372     int32_t baseVertex);
 373
 374 //////////////////////////////////////////////////////////////////////////
 375 /// @brief SwrDrawIndexedInstanced
 376 /// @param hContext - Handle passed back from SwrCreateContext
 377 /// @param topology - Specifies topology for draw.
 378 /// @param numIndices - Number of indices to read sequentially from index buffer.
 379 /// @param numInstances - Number of instances to render.
 380 /// @param indexOffset - Starting index into index buffer.
 381 /// @param baseVertex - Vertex in vertex buffer to consider as index "0". Note value is signed.
 382 /// @param startInstance - Which instance to start sequentially fetching from in each buffer (instanced data)
 383 void SWR_API SwrDrawIndexedInstanced(
 384     HANDLE hContext,
 385     PRIMITIVE_TOPOLOGY topology,
 386     uint32_t numIndices,
 387     uint32_t numInstances,
 388     uint32_t indexOffset,
 389     int32_t baseVertex,
 390     uint32_t startInstance);
 391
 392 //////////////////////////////////////////////////////////////////////////
 393 /// @brief SwrInvalidateTiles
 394 /// @param hContext - Handle passed back from SwrCreateContext
 395 /// @param attachmentMask - The mask specifies which surfaces attached to the hottiles to invalidate.
 396 void SWR_API SwrInvalidateTiles(
 397     HANDLE hContext,
 398     uint32_t attachmentMask);
 399
 400 //////////////////////////////////////////////////////////////////////////
 401 /// @brief SwrDiscardRect
 402 /// @param hContext - Handle passed back from SwrCreateContext
 403 /// @param attachmentMask - The mask specifies which surfaces attached to the hottiles to discard.
 404 /// @param rect - if rect is all zeros, the entire attachment surface will be discarded
 405 void SWR_API SwrDiscardRect(
 406     HANDLE hContext,
 407     uint32_t attachmentMask,
 408     SWR_RECT rect);
 409
 410 //////////////////////////////////////////////////////////////////////////
 411 /// @brief SwrDispatch
 412 /// @param hContext - Handle passed back from SwrCreateContext
 413 /// @param threadGroupCountX - Number of thread groups dispatched in X direction
 414 /// @param threadGroupCountY - Number of thread groups dispatched in Y direction
 415 /// @param threadGroupCountZ - Number of thread groups dispatched in Z direction
 416 void SWR_API SwrDispatch(
 417     HANDLE hContext,
 418     uint32_t threadGroupCountX,
 419     uint32_t threadGroupCountY,
 420     uint32_t threadGroupCountZ);
 421
 422
 423 enum SWR_TILE_STATE
 424 {
 425     SWR_TILE_INVALID    = 0,    // tile is in unitialized state and should be loaded with surface contents before rendering
 426     SWR_TILE_DIRTY      = 2,    // tile contains newer data than surface it represents
 427     SWR_TILE_RESOLVED   = 3,    // is in sync with surface it represents
 428 };
 429
 430 /// @todo Add a good description for what attachments are and when and why you would use the different SWR_TILE_STATEs.
 431 void SWR_API SwrStoreTiles(
 432     HANDLE hContext,
 433     SWR_RENDERTARGET_ATTACHMENT attachment,
 434     SWR_TILE_STATE postStoreTileState);
 435
 436 void SWR_API SwrClearRenderTarget(
 437     HANDLE hContext,
 438     uint32_t clearMask,
 439     const float clearColor[4],
 440     float z,
 441     uint8_t stencil);
 442
 443 void SWR_API SwrSetRastState(
 444     HANDLE hContext,
 445     const SWR_RASTSTATE *pRastState);
 446
 447 //////////////////////////////////////////////////////////////////////////
 448 /// @brief SwrSetViewports
 449 /// @param hContext - Handle passed back from SwrCreateContext
 450 /// @param numViewports - number of viewports passed in
 451 /// @param pViewports - Specifies extents of viewport.
 452 /// @param pMatrices - If not specified then SWR computes a default one.
 453 void SWR_API SwrSetViewports(
 454     HANDLE hContext,
 455     uint32_t numViewports,
 456     const SWR_VIEWPORT* pViewports,
 457     const SWR_VIEWPORT_MATRIX* pMatrices);
 458
 459 //////////////////////////////////////////////////////////////////////////
 460 /// @brief SwrSetScissorRects
 461 /// @param hContext - Handle passed back from SwrCreateContext
 462 /// @param numScissors - number of scissors passed in
 463 /// @param pScissors - array of scissors
 464 void SWR_API SwrSetScissorRects(
 465     HANDLE hContext,
 466     uint32_t numScissors,
 467     const BBOX* pScissors);
 468
 469 //////////////////////////////////////////////////////////////////////////
 470 /// @brief Returns a pointer to the private context state for the current
 471 ///        draw operation. This is used for external componets such as the
 472 ///        sampler.
 473 ///
 474 /// @note  Client needs to resend private state prior to each draw call.
 475 ///        Also, SWR is responsible for the private state memory.
 476 /// @param hContext - Handle passed back from SwrCreateContext
 477 VOID* SWR_API SwrGetPrivateContextState(
 478     HANDLE hContext);
 479
 480 //////////////////////////////////////////////////////////////////////////
 481 /// @brief Clients can use this to allocate memory for draw/dispatch
 482 ///        operations. The memory will automatically be freed once operation
 483 ///        has completed. Client can use this to allocate binding tables,
 484 ///        etc. needed for shader execution.
 485 /// @param hContext - Handle passed back from SwrCreateContext
 486 /// @param size - Size of allocation
 487 /// @param align - Alignment needed for allocation.
 488 VOID* SWR_API SwrAllocDrawContextMemory(
 489     HANDLE hContext,
 490     uint32_t size,
 491     uint32_t align);
 492
 493 //////////////////////////////////////////////////////////////////////////
 494 /// @brief Returns pointer to SWR stats.
 495 /// @note The counters are incremented by multiple threads.
 496 ///       When calling this, you need to ensure all previous operations
 497 ///       have completed.
 498 /// @param hContext - Handle passed back from SwrCreateContext
 499 /// @param pStats - SWR will fill this out for caller.
 500 void SWR_API SwrGetStats(
 501     HANDLE hContext,
 502     SWR_STATS* pStats);
 503
 504 //////////////////////////////////////////////////////////////////////////
 505 /// @brief Enables stats counting
 506 /// @param hContext - Handle passed back from SwrCreateContext
 507 /// @param enable - If true then counts are incremented.
 508 void SWR_API SwrEnableStats(
 509     HANDLE hContext,
 510     bool enable);
 511
 512 //////////////////////////////////////////////////////////////////////////
 513 /// @brief Mark end of frame - used for performance profiling
 514 /// @param hContext - Handle passed back from SwrCreateContext
 515 void SWR_API SwrEndFrame(
 516     HANDLE hContext);
 517 #endif//__SWR_API_H__