p_context.h revision 133a47107cc03a69b4b88c1fef331d507f521fa7
1/************************************************************************** 2 * 3 * Copyright 2007 VMware, Inc. 4 * All Rights Reserved. 5 * 6 * Permission is hereby granted, free of charge, to any person obtaining a 7 * copy of this software and associated documentation files (the 8 * "Software"), to deal in the Software without restriction, including 9 * without limitation the rights to use, copy, modify, merge, publish, 10 * distribute, sub license, and/or sell copies of the Software, and to 11 * permit persons to whom the Software is furnished to do so, subject to 12 * the following conditions: 13 * 14 * The above copyright notice and this permission notice (including the 15 * next paragraph) shall be included in all copies or substantial portions 16 * of the Software. 17 * 18 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 19 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 20 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. 21 * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR 22 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, 23 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 24 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 25 * 26 **************************************************************************/ 27 28#ifndef PIPE_CONTEXT_H 29#define PIPE_CONTEXT_H 30 31#include "p_compiler.h" 32#include "p_format.h" 33#include "p_video_enums.h" 34#include "p_defines.h" 35#include <stdio.h> 36 37#ifdef __cplusplus 38extern "C" { 39#endif 40 41 42struct pipe_blend_color; 43struct pipe_blend_state; 44struct pipe_blit_info; 45struct pipe_box; 46struct pipe_clip_state; 47struct pipe_constant_buffer; 48struct pipe_depth_stencil_alpha_state; 49struct pipe_draw_info; 50struct pipe_fence_handle; 51struct pipe_framebuffer_state; 52struct pipe_image_view; 53struct pipe_index_buffer; 54struct pipe_query; 55struct pipe_poly_stipple; 56struct pipe_rasterizer_state; 57struct pipe_resolve_info; 58struct pipe_resource; 59struct pipe_sampler_state; 60struct pipe_sampler_view; 61struct pipe_scissor_state; 62struct pipe_shader_buffer; 63struct pipe_shader_state; 64struct pipe_stencil_ref; 65struct pipe_stream_output_target; 66struct pipe_surface; 67struct pipe_transfer; 68struct pipe_vertex_buffer; 69struct pipe_vertex_element; 70struct pipe_video_buffer; 71struct pipe_video_codec; 72struct pipe_viewport_state; 73struct pipe_compute_state; 74union pipe_color_union; 75union pipe_query_result; 76 77/** 78 * Gallium rendering context. Basically: 79 * - state setting functions 80 * - VBO drawing functions 81 * - surface functions 82 */ 83struct pipe_context { 84 struct pipe_screen *screen; 85 86 void *priv; /**< context private data (for DRI for example) */ 87 void *draw; /**< private, for draw module (temporary?) */ 88 89 void (*destroy)( struct pipe_context * ); 90 91 /** 92 * VBO drawing 93 */ 94 /*@{*/ 95 void (*draw_vbo)( struct pipe_context *pipe, 96 const struct pipe_draw_info *info ); 97 /*@}*/ 98 99 /** 100 * Predicate subsequent rendering on occlusion query result 101 * \param query the query predicate, or NULL if no predicate 102 * \param condition whether to skip on FALSE or TRUE query results 103 * \param mode one of PIPE_RENDER_COND_x 104 */ 105 void (*render_condition)( struct pipe_context *pipe, 106 struct pipe_query *query, 107 boolean condition, 108 uint mode ); 109 110 /** 111 * Query objects 112 */ 113 /*@{*/ 114 struct pipe_query *(*create_query)( struct pipe_context *pipe, 115 unsigned query_type, 116 unsigned index ); 117 118 void (*destroy_query)(struct pipe_context *pipe, 119 struct pipe_query *q); 120 121 boolean (*begin_query)(struct pipe_context *pipe, struct pipe_query *q); 122 void (*end_query)(struct pipe_context *pipe, struct pipe_query *q); 123 124 /** 125 * Get results of a query. 126 * \param wait if true, this query will block until the result is ready 127 * \return TRUE if results are ready, FALSE otherwise 128 */ 129 boolean (*get_query_result)(struct pipe_context *pipe, 130 struct pipe_query *q, 131 boolean wait, 132 union pipe_query_result *result); 133 /*@}*/ 134 135 /** 136 * State functions (create/bind/destroy state objects) 137 */ 138 /*@{*/ 139 void * (*create_blend_state)(struct pipe_context *, 140 const struct pipe_blend_state *); 141 void (*bind_blend_state)(struct pipe_context *, void *); 142 void (*delete_blend_state)(struct pipe_context *, void *); 143 144 void * (*create_sampler_state)(struct pipe_context *, 145 const struct pipe_sampler_state *); 146 void (*bind_sampler_states)(struct pipe_context *, 147 unsigned shader, unsigned start_slot, 148 unsigned num_samplers, void **samplers); 149 void (*delete_sampler_state)(struct pipe_context *, void *); 150 151 void * (*create_rasterizer_state)(struct pipe_context *, 152 const struct pipe_rasterizer_state *); 153 void (*bind_rasterizer_state)(struct pipe_context *, void *); 154 void (*delete_rasterizer_state)(struct pipe_context *, void *); 155 156 void * (*create_depth_stencil_alpha_state)(struct pipe_context *, 157 const struct pipe_depth_stencil_alpha_state *); 158 void (*bind_depth_stencil_alpha_state)(struct pipe_context *, void *); 159 void (*delete_depth_stencil_alpha_state)(struct pipe_context *, void *); 160 161 void * (*create_fs_state)(struct pipe_context *, 162 const struct pipe_shader_state *); 163 void (*bind_fs_state)(struct pipe_context *, void *); 164 void (*delete_fs_state)(struct pipe_context *, void *); 165 166 void * (*create_vs_state)(struct pipe_context *, 167 const struct pipe_shader_state *); 168 void (*bind_vs_state)(struct pipe_context *, void *); 169 void (*delete_vs_state)(struct pipe_context *, void *); 170 171 void * (*create_gs_state)(struct pipe_context *, 172 const struct pipe_shader_state *); 173 void (*bind_gs_state)(struct pipe_context *, void *); 174 void (*delete_gs_state)(struct pipe_context *, void *); 175 176 void * (*create_tcs_state)(struct pipe_context *, 177 const struct pipe_shader_state *); 178 void (*bind_tcs_state)(struct pipe_context *, void *); 179 void (*delete_tcs_state)(struct pipe_context *, void *); 180 181 void * (*create_tes_state)(struct pipe_context *, 182 const struct pipe_shader_state *); 183 void (*bind_tes_state)(struct pipe_context *, void *); 184 void (*delete_tes_state)(struct pipe_context *, void *); 185 186 void * (*create_vertex_elements_state)(struct pipe_context *, 187 unsigned num_elements, 188 const struct pipe_vertex_element *); 189 void (*bind_vertex_elements_state)(struct pipe_context *, void *); 190 void (*delete_vertex_elements_state)(struct pipe_context *, void *); 191 192 /*@}*/ 193 194 /** 195 * Parameter-like state (or properties) 196 */ 197 /*@{*/ 198 void (*set_blend_color)( struct pipe_context *, 199 const struct pipe_blend_color * ); 200 201 void (*set_stencil_ref)( struct pipe_context *, 202 const struct pipe_stencil_ref * ); 203 204 void (*set_sample_mask)( struct pipe_context *, 205 unsigned sample_mask ); 206 207 void (*set_min_samples)( struct pipe_context *, 208 unsigned min_samples ); 209 210 void (*set_clip_state)( struct pipe_context *, 211 const struct pipe_clip_state * ); 212 213 void (*set_constant_buffer)( struct pipe_context *, 214 uint shader, uint index, 215 struct pipe_constant_buffer *buf ); 216 217 void (*set_framebuffer_state)( struct pipe_context *, 218 const struct pipe_framebuffer_state * ); 219 220 void (*set_polygon_stipple)( struct pipe_context *, 221 const struct pipe_poly_stipple * ); 222 223 void (*set_scissor_states)( struct pipe_context *, 224 unsigned start_slot, 225 unsigned num_scissors, 226 const struct pipe_scissor_state * ); 227 228 void (*set_viewport_states)( struct pipe_context *, 229 unsigned start_slot, 230 unsigned num_viewports, 231 const struct pipe_viewport_state *); 232 233 void (*set_sampler_views)(struct pipe_context *, unsigned shader, 234 unsigned start_slot, unsigned num_views, 235 struct pipe_sampler_view **); 236 237 void (*set_tess_state)(struct pipe_context *, 238 const float default_outer_level[4], 239 const float default_inner_level[2]); 240 241 /** 242 * Bind an array of shader buffers that will be used by a shader. 243 * Any buffers that were previously bound to the specified range 244 * will be unbound. 245 * 246 * \param shader selects shader stage 247 * \param start_slot first buffer slot to bind. 248 * \param count number of consecutive buffers to bind. 249 * \param buffers array of pointers to the buffers to bind, it 250 * should contain at least \a count elements 251 * unless it's NULL, in which case no buffers will 252 * be bound. 253 */ 254 void (*set_shader_buffers)(struct pipe_context *, unsigned shader, 255 unsigned start_slot, unsigned count, 256 struct pipe_shader_buffer *buffers); 257 258 /** 259 * Bind an array of images that will be used by a shader. 260 * Any images that were previously bound to the specified range 261 * will be unbound. 262 * 263 * \param shader selects shader stage 264 * \param start_slot first image slot to bind. 265 * \param count number of consecutive images to bind. 266 * \param buffers array of pointers to the images to bind, it 267 * should contain at least \a count elements 268 * unless it's NULL, in which case no images will 269 * be bound. 270 */ 271 void (*set_shader_images)(struct pipe_context *, unsigned shader, 272 unsigned start_slot, unsigned count, 273 struct pipe_image_view **images); 274 275 void (*set_vertex_buffers)( struct pipe_context *, 276 unsigned start_slot, 277 unsigned num_buffers, 278 const struct pipe_vertex_buffer * ); 279 280 void (*set_index_buffer)( struct pipe_context *pipe, 281 const struct pipe_index_buffer * ); 282 283 /*@}*/ 284 285 /** 286 * Stream output functions. 287 */ 288 /*@{*/ 289 290 struct pipe_stream_output_target *(*create_stream_output_target)( 291 struct pipe_context *, 292 struct pipe_resource *, 293 unsigned buffer_offset, 294 unsigned buffer_size); 295 296 void (*stream_output_target_destroy)(struct pipe_context *, 297 struct pipe_stream_output_target *); 298 299 void (*set_stream_output_targets)(struct pipe_context *, 300 unsigned num_targets, 301 struct pipe_stream_output_target **targets, 302 const unsigned *offsets); 303 304 /*@}*/ 305 306 307 /** 308 * Resource functions for blit-like functionality 309 * 310 * If a driver supports multisampling, blit must implement color resolve. 311 */ 312 /*@{*/ 313 314 /** 315 * Copy a block of pixels from one resource to another. 316 * The resource must be of the same format. 317 * Resources with nr_samples > 1 are not allowed. 318 */ 319 void (*resource_copy_region)(struct pipe_context *pipe, 320 struct pipe_resource *dst, 321 unsigned dst_level, 322 unsigned dstx, unsigned dsty, unsigned dstz, 323 struct pipe_resource *src, 324 unsigned src_level, 325 const struct pipe_box *src_box); 326 327 /* Optimal hardware path for blitting pixels. 328 * Scaling, format conversion, up- and downsampling (resolve) are allowed. 329 */ 330 void (*blit)(struct pipe_context *pipe, 331 const struct pipe_blit_info *info); 332 333 /*@}*/ 334 335 /** 336 * Clear the specified set of currently bound buffers to specified values. 337 * The entire buffers are cleared (no scissor, no colormask, etc). 338 * 339 * \param buffers bitfield of PIPE_CLEAR_* values. 340 * \param color pointer to a union of fiu array for each of r, g, b, a. 341 * \param depth depth clear value in [0,1]. 342 * \param stencil stencil clear value 343 */ 344 void (*clear)(struct pipe_context *pipe, 345 unsigned buffers, 346 const union pipe_color_union *color, 347 double depth, 348 unsigned stencil); 349 350 /** 351 * Clear a color rendertarget surface. 352 * \param color pointer to an union of fiu array for each of r, g, b, a. 353 */ 354 void (*clear_render_target)(struct pipe_context *pipe, 355 struct pipe_surface *dst, 356 const union pipe_color_union *color, 357 unsigned dstx, unsigned dsty, 358 unsigned width, unsigned height); 359 360 /** 361 * Clear a depth-stencil surface. 362 * \param clear_flags bitfield of PIPE_CLEAR_DEPTH/STENCIL values. 363 * \param depth depth clear value in [0,1]. 364 * \param stencil stencil clear value 365 */ 366 void (*clear_depth_stencil)(struct pipe_context *pipe, 367 struct pipe_surface *dst, 368 unsigned clear_flags, 369 double depth, 370 unsigned stencil, 371 unsigned dstx, unsigned dsty, 372 unsigned width, unsigned height); 373 374 /** 375 * Clear a buffer. Runs a memset over the specified region with the element 376 * value passed in through clear_value of size clear_value_size. 377 */ 378 void (*clear_buffer)(struct pipe_context *pipe, 379 struct pipe_resource *res, 380 unsigned offset, 381 unsigned size, 382 const void *clear_value, 383 int clear_value_size); 384 385 /** 386 * Flush draw commands 387 * 388 * NOTE: use screen->fence_reference() (or equivalent) to transfer 389 * new fence ref to **fence, to ensure that previous fence is unref'd 390 * 391 * \param fence if not NULL, an old fence to unref and transfer a 392 * new fence reference to 393 * \param flags bitfield of enum pipe_flush_flags values. 394 */ 395 void (*flush)(struct pipe_context *pipe, 396 struct pipe_fence_handle **fence, 397 unsigned flags); 398 399 /** 400 * Create a view on a texture to be used by a shader stage. 401 */ 402 struct pipe_sampler_view * (*create_sampler_view)(struct pipe_context *ctx, 403 struct pipe_resource *texture, 404 const struct pipe_sampler_view *templat); 405 406 void (*sampler_view_destroy)(struct pipe_context *ctx, 407 struct pipe_sampler_view *view); 408 409 410 /** 411 * Get a surface which is a "view" into a resource, used by 412 * render target / depth stencil stages. 413 */ 414 struct pipe_surface *(*create_surface)(struct pipe_context *ctx, 415 struct pipe_resource *resource, 416 const struct pipe_surface *templat); 417 418 void (*surface_destroy)(struct pipe_context *ctx, 419 struct pipe_surface *); 420 421 /** 422 * Create an image view into a buffer or texture to be used with load, 423 * store, and atomic instructions by a shader stage. 424 */ 425 struct pipe_image_view * (*create_image_view)(struct pipe_context *ctx, 426 struct pipe_resource *texture, 427 const struct pipe_image_view *templat); 428 429 void (*image_view_destroy)(struct pipe_context *ctx, 430 struct pipe_image_view *view); 431 432 /** 433 * Map a resource. 434 * 435 * Transfers are (by default) context-private and allow uploads to be 436 * interleaved with rendering. 437 * 438 * out_transfer will contain the transfer object that must be passed 439 * to all the other transfer functions. It also contains useful 440 * information (like texture strides). 441 */ 442 void *(*transfer_map)(struct pipe_context *, 443 struct pipe_resource *resource, 444 unsigned level, 445 unsigned usage, /* a combination of PIPE_TRANSFER_x */ 446 const struct pipe_box *, 447 struct pipe_transfer **out_transfer); 448 449 /* If transfer was created with WRITE|FLUSH_EXPLICIT, only the 450 * regions specified with this call are guaranteed to be written to 451 * the resource. 452 */ 453 void (*transfer_flush_region)( struct pipe_context *, 454 struct pipe_transfer *transfer, 455 const struct pipe_box *); 456 457 void (*transfer_unmap)(struct pipe_context *, 458 struct pipe_transfer *transfer); 459 460 /* One-shot transfer operation with data supplied in a user 461 * pointer. XXX: strides?? 462 */ 463 void (*transfer_inline_write)( struct pipe_context *, 464 struct pipe_resource *, 465 unsigned level, 466 unsigned usage, /* a combination of PIPE_TRANSFER_x */ 467 const struct pipe_box *, 468 const void *data, 469 unsigned stride, 470 unsigned layer_stride); 471 472 /** 473 * Flush any pending framebuffer writes and invalidate texture caches. 474 */ 475 void (*texture_barrier)(struct pipe_context *); 476 477 /** 478 * Flush caches according to flags. 479 */ 480 void (*memory_barrier)(struct pipe_context *, unsigned flags); 481 482 /** 483 * Creates a video codec for a specific video format/profile 484 */ 485 struct pipe_video_codec *(*create_video_codec)( struct pipe_context *context, 486 const struct pipe_video_codec *templat ); 487 488 /** 489 * Creates a video buffer as decoding target 490 */ 491 struct pipe_video_buffer *(*create_video_buffer)( struct pipe_context *context, 492 const struct pipe_video_buffer *templat ); 493 494 /** 495 * Compute kernel execution 496 */ 497 /*@{*/ 498 /** 499 * Define the compute program and parameters to be used by 500 * pipe_context::launch_grid. 501 */ 502 void *(*create_compute_state)(struct pipe_context *context, 503 const struct pipe_compute_state *); 504 void (*bind_compute_state)(struct pipe_context *, void *); 505 void (*delete_compute_state)(struct pipe_context *, void *); 506 507 /** 508 * Bind an array of shader resources that will be used by the 509 * compute program. Any resources that were previously bound to 510 * the specified range will be unbound after this call. 511 * 512 * \param start first resource to bind. 513 * \param count number of consecutive resources to bind. 514 * \param resources array of pointers to the resources to bind, it 515 * should contain at least \a count elements 516 * unless it's NULL, in which case no new 517 * resources will be bound. 518 */ 519 void (*set_compute_resources)(struct pipe_context *, 520 unsigned start, unsigned count, 521 struct pipe_surface **resources); 522 523 /** 524 * Bind an array of buffers to be mapped into the address space of 525 * the GLOBAL resource. Any buffers that were previously bound 526 * between [first, first + count - 1] are unbound after this call. 527 * 528 * \param first first buffer to map. 529 * \param count number of consecutive buffers to map. 530 * \param resources array of pointers to the buffers to map, it 531 * should contain at least \a count elements 532 * unless it's NULL, in which case no new 533 * resources will be bound. 534 * \param handles array of pointers to the memory locations that 535 * will be updated with the address each buffer 536 * will be mapped to. The base memory address of 537 * each of the buffers will be added to the value 538 * pointed to by its corresponding handle to form 539 * the final address argument. It should contain 540 * at least \a count elements, unless \a 541 * resources is NULL in which case \a handles 542 * should be NULL as well. 543 * 544 * Note that the driver isn't required to make any guarantees about 545 * the contents of the \a handles array being valid anytime except 546 * during the subsequent calls to pipe_context::launch_grid. This 547 * means that the only sensible location handles[i] may point to is 548 * somewhere within the INPUT buffer itself. This is so to 549 * accommodate implementations that lack virtual memory but 550 * nevertheless migrate buffers on the fly, leading to resource 551 * base addresses that change on each kernel invocation or are 552 * unknown to the pipe driver. 553 */ 554 void (*set_global_binding)(struct pipe_context *context, 555 unsigned first, unsigned count, 556 struct pipe_resource **resources, 557 uint32_t **handles); 558 559 /** 560 * Launch the compute kernel starting from instruction \a pc of the 561 * currently bound compute program. 562 * 563 * \a grid_layout and \a block_layout are arrays of size \a 564 * PIPE_COMPUTE_CAP_GRID_DIMENSION that determine the layout of the 565 * grid (in block units) and working block (in thread units) to be 566 * used, respectively. 567 * 568 * \a pc For drivers that use PIPE_SHADER_IR_LLVM as their prefered IR, 569 * this value will be the index of the kernel in the opencl.kernels 570 * metadata list. 571 * 572 * \a input will be used to initialize the INPUT resource, and it 573 * should point to a buffer of at least 574 * pipe_compute_state::req_input_mem bytes. 575 */ 576 void (*launch_grid)(struct pipe_context *context, 577 const uint *block_layout, const uint *grid_layout, 578 uint32_t pc, const void *input); 579 /*@}*/ 580 581 /** 582 * Get sample position for an individual sample point. 583 * 584 * \param sample_count - total number of samples 585 * \param sample_index - sample to get the position values for 586 * \param out_value - return value of 2 floats for x and y position for 587 * requested sample. 588 */ 589 void (*get_sample_position)(struct pipe_context *context, 590 unsigned sample_count, 591 unsigned sample_index, 592 float *out_value); 593 594 /** 595 * Query a timestamp in nanoseconds. This is completely equivalent to 596 * pipe_screen::get_timestamp() but takes a context handle for drivers 597 * that require a context. 598 */ 599 uint64_t (*get_timestamp)(struct pipe_context *); 600 601 /** 602 * Flush the resource cache, so that the resource can be used 603 * by an external client. Possible usage: 604 * - flushing a resource before presenting it on the screen 605 * - flushing a resource if some other process or device wants to use it 606 * This shouldn't be used to flush caches if the resource is only managed 607 * by a single pipe_screen and is not shared with another process. 608 * (i.e. you shouldn't use it to flush caches explicitly if you want to e.g. 609 * use the resource for texturing) 610 */ 611 void (*flush_resource)(struct pipe_context *ctx, 612 struct pipe_resource *resource); 613 614 /** 615 * Invalidate the contents of the resource. 616 * 617 * This is used to implement EGL's semantic of undefined depth/stencil 618 * contenst after a swapbuffers. This allows a tiled renderer (for 619 * example) to not store the depth buffer. 620 */ 621 void (*invalidate_resource)(struct pipe_context *ctx, 622 struct pipe_resource *resource); 623 624 /** 625 * Return information about unexpected device resets. 626 */ 627 enum pipe_reset_status (*get_device_reset_status)(struct pipe_context *ctx); 628 629 /** 630 * Dump driver-specific debug information into a stream. This is 631 * used by debugging tools. 632 * 633 * \param ctx pipe context 634 * \param stream where the output should be written to 635 * \param flags a mask of PIPE_DEBUG_* flags 636 */ 637 void (*dump_debug_state)(struct pipe_context *ctx, FILE *stream, 638 unsigned flags); 639}; 640 641 642#ifdef __cplusplus 643} 644#endif 645 646#endif /* PIPE_CONTEXT_H */ 647