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, BYTE *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, BYTE *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 //////////////////////////////////////////////////////////////////////////
  81 /// SWR_CREATECONTEXT_INFO
  82 /////////////////////////////////////////////////////////////////////////
  83 struct SWR_CREATECONTEXT_INFO
  84 {
  85     DRIVER_TYPE driver;
  86
  87     // External functions (e.g. sampler) need per draw context state.
  88     // Use SwrGetPrivateContextState() to access private state.
  89     uint32_t privateStateSize;
  90
  91     // Each SWR context can have multiple sets of active state
  92     uint32_t maxSubContexts;
  93
  94     // tile manipulation functions
  95     PFN_LOAD_TILE pfnLoadTile;
  96     PFN_STORE_TILE pfnStoreTile;
  97     PFN_CLEAR_TILE pfnClearTile;
  98 };
  99
 100 //////////////////////////////////////////////////////////////////////////
 101 /// SWR_RECT
 102 /////////////////////////////////////////////////////////////////////////
 103 struct SWR_RECT
 104 {
 105     uint32_t left;
 106     uint32_t right;
 107     uint32_t top;
 108     uint32_t bottom;
 109 };
 110
 111 //////////////////////////////////////////////////////////////////////////
 112 /// @brief Create SWR Context.
 113 /// @param pCreateInfo - pointer to creation info.
 114 HANDLE SWR_API SwrCreateContext(
 115     const SWR_CREATECONTEXT_INFO* pCreateInfo);
 116
 117 //////////////////////////////////////////////////////////////////////////
 118 /// @brief Destroys SWR Context.
 119 /// @param hContext - Handle passed back from SwrCreateContext
 120 void SWR_API SwrDestroyContext(
 121     HANDLE hContext);
 122
 123 //////////////////////////////////////////////////////////////////////////
 124 /// @brief Set currently active state context
 125 /// @param subContextIndex - value from 0 to
 126 ///     SWR_CREATECONTEXT_INFO.maxSubContexts.  Defaults to 0.
 127 void SWR_API SwrSetActiveSubContext(
 128     HANDLE hContext,
 129     uint32_t subContextIndex);
 130
 131 //////////////////////////////////////////////////////////////////////////
 132 /// @brief Sync cmd. Executes the callback func when all rendering up to this sync
 133 ///        has been completed
 134 /// @param hContext - Handle passed back from SwrCreateContext
 135 /// @param pfnFunc - pointer to callback function,
 136 /// @param userData - user data to pass back
 137 void SWR_API SwrSync(
 138     HANDLE hContext,
 139     PFN_CALLBACK_FUNC pfnFunc,
 140     uint64_t userData,
 141     uint64_t userData2,
 142     uint64_t userData3 = 0);
 143
 144 //////////////////////////////////////////////////////////////////////////
 145 /// @brief Blocks until all rendering has been completed.
 146 /// @param hContext - Handle passed back from SwrCreateContext
 147 void SWR_API SwrWaitForIdle(
 148     HANDLE hContext);
 149
 150 //////////////////////////////////////////////////////////////////////////
 151 /// @brief Set vertex buffer state.
 152 /// @param hContext - Handle passed back from SwrCreateContext
 153 /// @param numBuffers - Number of vertex buffer state descriptors.
 154 /// @param pVertexBuffers - Array of vertex buffer state descriptors.
 155 void SWR_API SwrSetVertexBuffers(
 156     HANDLE hContext,
 157     uint32_t numBuffers,
 158     const SWR_VERTEX_BUFFER_STATE* pVertexBuffers);
 159
 160 //////////////////////////////////////////////////////////////////////////
 161 /// @brief Set index buffer
 162 /// @param hContext - Handle passed back from SwrCreateContext
 163 /// @param pIndexBuffer - Index buffer.
 164 void SWR_API SwrSetIndexBuffer(
 165     HANDLE hContext,
 166     const SWR_INDEX_BUFFER_STATE* pIndexBuffer);
 167
 168 //////////////////////////////////////////////////////////////////////////
 169 /// @brief Set fetch shader pointer.
 170 /// @param hContext - Handle passed back from SwrCreateContext
 171 /// @param pfnFetchFunc - Pointer to shader.
 172 void SWR_API SwrSetFetchFunc(
 173     HANDLE hContext,
 174     PFN_FETCH_FUNC    pfnFetchFunc);
 175
 176 //////////////////////////////////////////////////////////////////////////
 177 /// @brief Set streamout shader pointer.
 178 /// @param hContext - Handle passed back from SwrCreateContext
 179 /// @param pfnSoFunc - Pointer to shader.
 180 /// @param streamIndex - specifies stream
 181 void SWR_API SwrSetSoFunc(
 182     HANDLE hContext,
 183     PFN_SO_FUNC    pfnSoFunc,
 184     uint32_t streamIndex);
 185
 186 //////////////////////////////////////////////////////////////////////////
 187 /// @brief Set streamout state
 188 /// @param hContext - Handle passed back from SwrCreateContext
 189 /// @param pSoState - Pointer to streamout state.
 190 void SWR_API SwrSetSoState(
 191     HANDLE hContext,
 192     SWR_STREAMOUT_STATE* pSoState);
 193
 194 //////////////////////////////////////////////////////////////////////////
 195 /// @brief Set streamout buffer state
 196 /// @param hContext - Handle passed back from SwrCreateContext
 197 /// @param pSoBuffer - Pointer to streamout buffer.
 198 /// @param slot - Slot to bind SO buffer to.
 199 void SWR_API SwrSetSoBuffers(
 200     HANDLE hContext,
 201     SWR_STREAMOUT_BUFFER* pSoBuffer,
 202     uint32_t slot);
 203
 204 //////////////////////////////////////////////////////////////////////////
 205 /// @brief Set vertex shader pointer.
 206 /// @param hContext - Handle passed back from SwrCreateContext
 207 /// @param pfnVertexFunc - Pointer to shader.
 208 void SWR_API SwrSetVertexFunc(
 209     HANDLE hContext,
 210     PFN_VERTEX_FUNC pfnVertexFunc);
 211
 212 //////////////////////////////////////////////////////////////////////////
 213 /// @brief Set frontend state.
 214 /// @param hContext - Handle passed back from SwrCreateContext
 215 /// @param pState - Pointer to state
 216 void SWR_API SwrSetFrontendState(
 217     HANDLE hContext,
 218     SWR_FRONTEND_STATE *pState);
 219
 220 //////////////////////////////////////////////////////////////////////////
 221 /// @brief Set geometry shader state.
 222 /// @param hContext - Handle passed back from SwrCreateContext
 223 /// @param pState - Pointer to state
 224 void SWR_API SwrSetGsState(
 225     HANDLE hContext,
 226     SWR_GS_STATE *pState);
 227
 228 //////////////////////////////////////////////////////////////////////////
 229 /// @brief Set geometry shader
 230 /// @param hContext - Handle passed back from SwrCreateContext
 231 /// @param pState - Pointer to geometry shader function
 232 void SWR_API SwrSetGsFunc(
 233     HANDLE hContext,
 234     PFN_GS_FUNC pfnGsFunc);
 235
 236 //////////////////////////////////////////////////////////////////////////
 237 /// @brief Set compute shader
 238 /// @param hContext - Handle passed back from SwrCreateContext
 239 /// @param pState - Pointer to compute shader function
 240 /// @param totalThreadsInGroup - product of thread group dimensions.
 241 void SWR_API SwrSetCsFunc(
 242     HANDLE hContext,
 243     PFN_CS_FUNC pfnCsFunc,
 244     uint32_t totalThreadsInGroup);
 245
 246 //////////////////////////////////////////////////////////////////////////
 247 /// @brief Set tessellation state.
 248 /// @param hContext - Handle passed back from SwrCreateContext
 249 /// @param pState - Pointer to state
 250 void SWR_API SwrSetTsState(
 251     HANDLE hContext,
 252     SWR_TS_STATE *pState);
 253
 254 //////////////////////////////////////////////////////////////////////////
 255 /// @brief Set hull shader
 256 /// @param hContext - Handle passed back from SwrCreateContext
 257 /// @param pfnFunc - Pointer to shader function
 258 void SWR_API SwrSetHsFunc(
 259     HANDLE hContext,
 260     PFN_HS_FUNC pfnFunc);
 261
 262 //////////////////////////////////////////////////////////////////////////
 263 /// @brief Set domain shader
 264 /// @param hContext - Handle passed back from SwrCreateContext
 265 /// @param pfnFunc - Pointer to shader function
 266 void SWR_API SwrSetDsFunc(
 267     HANDLE hContext,
 268     PFN_DS_FUNC pfnFunc);
 269
 270 //////////////////////////////////////////////////////////////////////////
 271 /// @brief Set depth stencil state
 272 /// @param hContext - Handle passed back from SwrCreateContext
 273 /// @param pState - Pointer to state.
 274 void SWR_API SwrSetDepthStencilState(
 275     HANDLE hContext,
 276     SWR_DEPTH_STENCIL_STATE *pState);
 277
 278 //////////////////////////////////////////////////////////////////////////
 279 /// @brief Set backend state
 280 /// @param hContext - Handle passed back from SwrCreateContext
 281 /// @param pState - Pointer to state.
 282 void SWR_API SwrSetBackendState(
 283     HANDLE hContext,
 284     SWR_BACKEND_STATE *pState);
 285
 286 //////////////////////////////////////////////////////////////////////////
 287 /// @brief Set pixel shader state
 288 /// @param hContext - Handle passed back from SwrCreateContext
 289 /// @param pState - Pointer to state.
 290 void SWR_API SwrSetPixelShaderState(
 291     HANDLE hContext,
 292     SWR_PS_STATE *pState);
 293
 294 //////////////////////////////////////////////////////////////////////////
 295 /// @brief Set blend state
 296 /// @param hContext - Handle passed back from SwrCreateContext
 297 /// @param pState - Pointer to state.
 298 void SWR_API SwrSetBlendState(
 299     HANDLE hContext,
 300     SWR_BLEND_STATE *pState);
 301
 302 //////////////////////////////////////////////////////////////////////////
 303 /// @brief Set blend function
 304 /// @param hContext - Handle passed back from SwrCreateContext
 305 /// @param renderTarget - render target index
 306 /// @param pfnBlendFunc - function pointer
 307 void SWR_API SwrSetBlendFunc(
 308     HANDLE hContext,
 309     uint32_t renderTarget,
 310     PFN_BLEND_JIT_FUNC pfnBlendFunc);
 311
 312 //////////////////////////////////////////////////////////////////////////
 313 /// @brief Set linkage mask
 314 /// @param hContext - Handle passed back from SwrCreateContext
 315 /// @param mask - Specifies which vertex outputs are are needed by PS.
 316 /// @param pMap - (Optional)Linkage map to specify where FE attributes are
 317 ///               gathered from to supply PS attribute values.  The length
 318 ///               of the map buffer needs to match the number of set bits
 319 ///               in "mask".
 320 void SWR_API SwrSetLinkage(
 321     HANDLE hContext,
 322     uint32_t mask,
 323     const uint8_t* pMap);
 324
 325 //////////////////////////////////////////////////////////////////////////
 326 /// @brief SwrDraw
 327 /// @param hContext - Handle passed back from SwrCreateContext
 328 /// @param topology - Specifies topology for draw.
 329 /// @param startVertex - Specifies start vertex in vertex buffer for draw.
 330 /// @param primCount - Number of vertices.
 331 void SWR_API SwrDraw(
 332     HANDLE hContext,
 333     PRIMITIVE_TOPOLOGY topology,
 334     uint32_t startVertex,
 335     uint32_t primCount);
 336
 337 //////////////////////////////////////////////////////////////////////////
 338 /// @brief SwrDrawInstanced
 339 /// @param hContext - Handle passed back from SwrCreateContext
 340 /// @param topology - Specifies topology for draw.
 341 /// @param numVertsPerInstance - How many vertices to read sequentially from vertex data.
 342 /// @param numInstances - How many instances to render.
 343 /// @param startVertex - Specifies start vertex for draw. (vertex data)
 344 /// @param startInstance - Which instance to start sequentially fetching from in each buffer (instanced data)
 345 void SWR_API SwrDrawInstanced(
 346     HANDLE hContext,
 347     PRIMITIVE_TOPOLOGY topology,
 348     uint32_t numVertsPerInstance,
 349     uint32_t numInstances,
 350     uint32_t startVertex,
 351     uint32_t startInstance);
 352
 353 //////////////////////////////////////////////////////////////////////////
 354 /// @brief DrawIndexed
 355 /// @param hContext - Handle passed back from SwrCreateContext
 356 /// @param topology - Specifies topology for draw.
 357 /// @param numIndices - Number of indices to read sequentially from index buffer.
 358 /// @param indexOffset - Starting index into index buffer.
 359 /// @param baseVertex - Vertex in vertex buffer to consider as index "0". Note value is signed.
 360 void SWR_API SwrDrawIndexed(
 361     HANDLE hContext,
 362     PRIMITIVE_TOPOLOGY topology,
 363     uint32_t numIndices,
 364     uint32_t indexOffset,
 365     int32_t baseVertex);
 366
 367 //////////////////////////////////////////////////////////////////////////
 368 /// @brief SwrDrawIndexedInstanced
 369 /// @param hContext - Handle passed back from SwrCreateContext
 370 /// @param topology - Specifies topology for draw.
 371 /// @param numIndices - Number of indices to read sequentially from index buffer.
 372 /// @param numInstances - Number of instances to render.
 373 /// @param indexOffset - Starting index into index buffer.
 374 /// @param baseVertex - Vertex in vertex buffer to consider as index "0". Note value is signed.
 375 /// @param startInstance - Which instance to start sequentially fetching from in each buffer (instanced data)
 376 void SWR_API SwrDrawIndexedInstanced(
 377     HANDLE hContext,
 378     PRIMITIVE_TOPOLOGY topology,
 379     uint32_t numIndices,
 380     uint32_t numInstances,
 381     uint32_t indexOffset,
 382     int32_t baseVertex,
 383     uint32_t startInstance);
 384
 385 //////////////////////////////////////////////////////////////////////////
 386 /// @brief SwrInvalidateTiles
 387 /// @param hContext - Handle passed back from SwrCreateContext
 388 /// @param attachmentMask - The mask specifies which surfaces attached to the hottiles to invalidate.
 389 void SWR_API SwrInvalidateTiles(
 390     HANDLE hContext,
 391     uint32_t attachmentMask);
 392
 393 //////////////////////////////////////////////////////////////////////////
 394 /// @brief SwrDispatch
 395 /// @param hContext - Handle passed back from SwrCreateContext
 396 /// @param threadGroupCountX - Number of thread groups dispatched in X direction
 397 /// @param threadGroupCountY - Number of thread groups dispatched in Y direction
 398 /// @param threadGroupCountZ - Number of thread groups dispatched in Z direction
 399 void SWR_API SwrDispatch(
 400     HANDLE hContext,
 401     uint32_t threadGroupCountX,
 402     uint32_t threadGroupCountY,
 403     uint32_t threadGroupCountZ);
 404
 405
 406 enum SWR_TILE_STATE
 407 {
 408     SWR_TILE_INVALID    = 0,    // tile is in unitialized state and should be loaded with surface contents before rendering
 409     SWR_TILE_DIRTY      = 2,    // tile contains newer data than surface it represents
 410     SWR_TILE_RESOLVED   = 3,    // is in sync with surface it represents
 411 };
 412
 413 /// @todo Add a good description for what attachments are and when and why you would use the different SWR_TILE_STATEs.
 414 void SWR_API SwrStoreTiles(
 415     HANDLE hContext,
 416     SWR_RENDERTARGET_ATTACHMENT attachment,
 417     SWR_TILE_STATE postStoreTileState);
 418
 419 void SWR_API SwrClearRenderTarget(
 420     HANDLE hContext,
 421     uint32_t clearMask,
 422     const FLOAT clearColor[4],
 423     float z,
 424     BYTE stencil);
 425
 426 void SWR_API SwrSetRastState(
 427     HANDLE hContext,
 428     const SWR_RASTSTATE *pRastState);
 429
 430 //////////////////////////////////////////////////////////////////////////
 431 /// @brief SwrSetViewports
 432 /// @param hContext - Handle passed back from SwrCreateContext
 433 /// @param numViewports - number of viewports passed in
 434 /// @param pViewports - Specifies extents of viewport.
 435 /// @param pMatrices - If not specified then SWR computes a default one.
 436 void SWR_API SwrSetViewports(
 437     HANDLE hContext,
 438     uint32_t numViewports,
 439     const SWR_VIEWPORT* pViewports,
 440     const SWR_VIEWPORT_MATRIX* pMatrices);
 441
 442 //////////////////////////////////////////////////////////////////////////
 443 /// @brief SwrSetScissorRects
 444 /// @param hContext - Handle passed back from SwrCreateContext
 445 /// @param numScissors - number of scissors passed in
 446 /// @param pScissors - array of scissors
 447 void SWR_API SwrSetScissorRects(
 448     HANDLE hContext,
 449     uint32_t numScissors,
 450     const BBOX* pScissors);
 451
 452 //////////////////////////////////////////////////////////////////////////
 453 /// @brief Returns a pointer to the private context state for the current
 454 ///        draw operation. This is used for external componets such as the
 455 ///        sampler.
 456 ///
 457 /// @note  Client needs to resend private state prior to each draw call.
 458 ///        Also, SWR is responsible for the private state memory.
 459 /// @param hContext - Handle passed back from SwrCreateContext
 460 VOID* SWR_API SwrGetPrivateContextState(
 461     HANDLE hContext);
 462
 463 //////////////////////////////////////////////////////////////////////////
 464 /// @brief Clients can use this to allocate memory for draw/dispatch
 465 ///        operations. The memory will automatically be freed once operation
 466 ///        has completed. Client can use this to allocate binding tables,
 467 ///        etc. needed for shader execution.
 468 /// @param hContext - Handle passed back from SwrCreateContext
 469 /// @param size - Size of allocation
 470 /// @param align - Alignment needed for allocation.
 471 VOID* SWR_API SwrAllocDrawContextMemory(
 472     HANDLE hContext,
 473     uint32_t size,
 474     uint32_t align);
 475
 476 //////////////////////////////////////////////////////////////////////////
 477 /// @brief Returns pointer to SWR stats.
 478 /// @note The counters are incremented by multiple threads.
 479 ///       When calling this, you need to ensure all previous operations
 480 ///       have completed.
 481 /// @param hContext - Handle passed back from SwrCreateContext
 482 /// @param pStats - SWR will fill this out for caller.
 483 void SWR_API SwrGetStats(
 484     HANDLE hContext,
 485     SWR_STATS* pStats);
 486
 487 //////////////////////////////////////////////////////////////////////////
 488 /// @brief Enables stats counting
 489 /// @param hContext - Handle passed back from SwrCreateContext
 490 /// @param enable - If true then counts are incremented.
 491 void SWR_API SwrEnableStats(
 492     HANDLE hContext,
 493     bool enable);
 494
 495 //////////////////////////////////////////////////////////////////////////
 496 /// @brief Mark end of frame - used for performance profiling
 497 /// @param hContext - Handle passed back from SwrCreateContext
 498 void SWR_API SwrEndFrame(
 499     HANDLE hContext);
 500 #endif//__SWR_API_H__