2 * Copyright 2006 VMware, Inc.
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the
7 * "Software"), to deal in the Software without restriction, including
8 * without limitation the rights to use, copy, modify, merge, publish,
9 * distribute, sublicense, and/or sell copies of the Software, and to
10 * permit persons to whom the Software is furnished to do so, subject to
11 * the following conditions:
13 * The above copyright notice and this permission notice (including the
14 * next paragraph) shall be included in all copies or substantial portions
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 * IN NO EVENT SHALL VMWARE AND/OR ITS SUPPLIERS BE LIABLE FOR
21 * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
26 /** @file intel_mipmap_tree.h
28 * This file defines the structure that wraps a BO and describes how the
29 * mipmap levels and slices of a texture are laid out.
31 * The hardware has a fixed layout of a texture depending on parameters such
32 * as the target/type (2D, 3D, CUBE), width, height, pitch, and number of
33 * mipmap levels. The individual level/layer slices are each 2D rectangles of
34 * pixels at some x/y offset from the start of the brw_bo.
36 * Original OpenGL allowed texture miplevels to be specified in arbitrary
37 * order, and a texture may change size over time. Thus, each
38 * intel_texture_image has a reference to a miptree that contains the pixel
39 * data sized appropriately for it, which will later be referenced by/copied
40 * to the intel_texture_object at draw time (intel_finalize_mipmap_tree()) so
41 * that there's a single miptree for the complete texture.
44 #ifndef INTEL_MIPMAP_TREE_H
45 #define INTEL_MIPMAP_TREE_H
49 #include "main/mtypes.h"
51 #include "blorp/blorp.h"
52 #include "brw_bufmgr.h"
53 #include "brw_context.h"
54 #include <GL/internal/dri_interface.h>
61 struct intel_renderbuffer
;
63 struct intel_texture_image
;
66 * This bit extends the set of GL_MAP_*_BIT enums.
68 * When calling intel_miptree_map() on an ETC-transcoded-to-RGB miptree or a
69 * depthstencil-split-to-separate-stencil miptree, we'll normally make a
70 * temporary and recreate the kind of data requested by Mesa core, since we're
71 * satisfying some glGetTexImage() request or something.
73 * However, occasionally you want to actually map the miptree's current data
74 * without transcoding back. This flag to intel_miptree_map() gets you that.
76 #define BRW_MAP_DIRECT_BIT 0x80000000
78 struct intel_miptree_map
{
79 /** Bitfield of GL_MAP_*_BIT and BRW_MAP_*_BIT. */
81 /** Region of interest for the map. */
83 /** Possibly malloced temporary buffer for the mapping. */
85 /** Possible pointer to a temporary linear miptree for the mapping. */
86 struct intel_mipmap_tree
*linear_mt
;
87 /** Pointer to the start of (map_x, map_y) returned by the mapping. */
89 /** Stride of the mapping. */
92 void (*unmap
)(struct brw_context
*brw
,
93 struct intel_mipmap_tree
*mt
,
94 struct intel_miptree_map
*map
,
100 * Describes the location of each texture image within a miptree.
102 struct intel_mipmap_level
104 /** Offset to this miptree level, used in computing x_offset. */
106 /** Offset to this miptree level, used in computing y_offset. */
110 * \brief Is HiZ enabled for this level?
112 * If \c mt->level[l].has_hiz is set, then (1) \c mt->hiz_mt has been
113 * allocated and (2) the HiZ memory for the slices in this level reside at
114 * \c mt->hiz_mt->level[l].
119 * \brief List of 2D images in this mipmap level.
121 * This may be a list of cube faces, array slices in 2D array texture, or
122 * layers in a 3D texture. The list's length is \c depth.
124 struct intel_mipmap_slice
{
126 * Mapping information. Persistent for the duration of
127 * intel_miptree_map/unmap on this slice.
129 struct intel_miptree_map
*map
;
134 * Miptree aux buffer. These buffers are associated with a miptree, but the
135 * format is managed by the hardware.
137 * For Gen7+, we always give the hardware the start of the buffer, and let it
138 * handle all accesses to the buffer. Therefore we don't need the full miptree
139 * layout structure for this buffer.
141 struct intel_miptree_aux_buffer
143 struct isl_surf surf
;
146 * Buffer object containing the pixel data.
148 * @see RENDER_SURFACE_STATE.AuxiliarySurfaceBaseAddress
149 * @see 3DSTATE_HIER_DEPTH_BUFFER.AuxiliarySurfaceBaseAddress
154 * Offset into bo where the surface starts.
156 * @see intel_mipmap_aux_buffer::bo
158 * @see RENDER_SURFACE_STATE.AuxiliarySurfaceBaseAddress
159 * @see 3DSTATE_DEPTH_BUFFER.SurfaceBaseAddress
160 * @see 3DSTATE_HIER_DEPTH_BUFFER.SurfaceBaseAddress
161 * @see 3DSTATE_STENCIL_BUFFER.SurfaceBaseAddress
166 * Buffer object containing the indirect clear color.
168 * @see create_ccs_buf_for_image
169 * @see RENDER_SURFACE_STATE.ClearValueAddress
171 struct brw_bo
*clear_color_bo
;
174 * Offset into bo where the clear color can be found.
176 * @see create_ccs_buf_for_image
177 * @see RENDER_SURFACE_STATE.ClearValueAddress
179 uint32_t clear_color_offset
;
182 struct intel_mipmap_tree
184 struct isl_surf surf
;
187 * Buffer object containing the surface.
189 * @see intel_mipmap_tree::offset
190 * @see RENDER_SURFACE_STATE.SurfaceBaseAddress
191 * @see RENDER_SURFACE_STATE.AuxiliarySurfaceBaseAddress
192 * @see 3DSTATE_DEPTH_BUFFER.SurfaceBaseAddress
193 * @see 3DSTATE_HIER_DEPTH_BUFFER.SurfaceBaseAddress
194 * @see 3DSTATE_STENCIL_BUFFER.SurfaceBaseAddress
199 * @brief One of GL_TEXTURE_2D, GL_TEXTURE_2D_ARRAY, etc.
201 * @see RENDER_SURFACE_STATE.SurfaceType
202 * @see RENDER_SURFACE_STATE.SurfaceArray
203 * @see 3DSTATE_DEPTH_BUFFER.SurfaceType
208 * Generally, this is just the same as the gl_texture_image->TexFormat or
209 * gl_renderbuffer->Format.
211 * However, for textures and renderbuffers with packed depth/stencil formats
212 * on hardware where we want or need to use separate stencil, there will be
213 * two miptrees for storing the data. If the depthstencil texture or rb is
214 * MESA_FORMAT_Z32_FLOAT_S8X24_UINT, then mt->format will be
215 * MESA_FORMAT_Z_FLOAT32, otherwise for MESA_FORMAT_Z24_UNORM_S8_UINT objects it will be
216 * MESA_FORMAT_Z24_UNORM_X8_UINT.
218 * For ETC1/ETC2 textures, this is one of the uncompressed mesa texture
219 * formats if the hardware lacks support for ETC1/ETC2. See @ref etc_format.
221 * @see RENDER_SURFACE_STATE.SurfaceFormat
222 * @see 3DSTATE_DEPTH_BUFFER.SurfaceFormat
227 * This variable stores the value of ETC compressed texture format
229 * @see RENDER_SURFACE_STATE.SurfaceFormat
231 mesa_format etc_format
;
236 /** Bytes per pixel (or bytes per block if compressed) */
241 /* Includes image offset tables: */
242 struct intel_mipmap_level level
[MAX_TEXTURE_LEVELS
];
245 * Offset into bo where the surface starts.
247 * @see intel_mipmap_tree::bo
249 * @see RENDER_SURFACE_STATE.AuxiliarySurfaceBaseAddress
250 * @see 3DSTATE_DEPTH_BUFFER.SurfaceBaseAddress
251 * @see 3DSTATE_HIER_DEPTH_BUFFER.SurfaceBaseAddress
252 * @see 3DSTATE_STENCIL_BUFFER.SurfaceBaseAddress
257 * \brief The type of auxiliary compression used by this miptree.
259 * This describes the type of auxiliary compression that is intended to be
260 * used by this miptree. An aux usage of ISL_AUX_USAGE_NONE means that
261 * auxiliary compression is permanently disabled. An aux usage other than
262 * ISL_AUX_USAGE_NONE does not imply that the auxiliary buffer has actually
263 * been allocated nor does it imply that auxiliary compression will always
264 * be enabled for this surface. For instance, with CCS_D, we may allocate
265 * the CCS on-the-fly and it may not be used for texturing if the miptree
268 enum isl_aux_usage aux_usage
;
271 * \brief Whether or not this miptree supports fast clears.
273 bool supports_fast_clear
;
276 * \brief Maps miptree slices to their current aux state
278 * This two-dimensional array is indexed as [level][layer] and stores an
279 * aux state for each slice.
281 enum isl_aux_state
**aux_state
;
284 * \brief Stencil miptree for depthstencil textures.
286 * This miptree is used for depthstencil textures and renderbuffers that
287 * require separate stencil. It always has the true copy of the stencil
288 * bits, regardless of mt->format.
290 * \see 3DSTATE_STENCIL_BUFFER
291 * \see intel_miptree_map_depthstencil()
292 * \see intel_miptree_unmap_depthstencil()
294 struct intel_mipmap_tree
*stencil_mt
;
297 * \brief Stencil texturing miptree for sampling from a stencil texture
299 * Some hardware doesn't support sampling from the stencil texture as
300 * required by the GL_ARB_stencil_texturing extenion. To workaround this we
301 * blit the texture into a new texture that can be sampled.
303 * \see intel_update_r8stencil()
305 struct intel_mipmap_tree
*r8stencil_mt
;
306 bool r8stencil_needs_update
;
309 * \brief CCS, MCS, or HiZ auxiliary buffer.
311 * NULL if no auxiliary buffer is in use for this surface.
313 * For single-sampled color miptrees:
314 * This buffer contains the Color Control Surface, which stores the
315 * necessary information to implement lossless color compression (CCS_E)
316 * and "fast color clear" (CCS_D) behaviour.
318 * For multi-sampled color miptrees:
319 * This buffer contains the Multisample Control Surface, which stores the
320 * necessary information to implement compressed MSAA
321 * (INTEL_MSAA_FORMAT_CMS).
323 * For depth miptrees:
324 * This buffer contains the Hierarchical Depth Buffer, which stores the
325 * necessary information to implement lossless depth compression and fast
326 * depth clear behavior.
328 * To determine if HiZ is enabled, do not check this pointer. Instead,
329 * use intel_miptree_level_has_hiz().
331 struct intel_miptree_aux_buffer
*aux_buf
;
334 * Planes 1 and 2 in case this is a planar surface.
336 struct intel_mipmap_tree
*plane
[2];
339 * Fast clear color for this surface. For depth surfaces, the clear value
340 * is stored as a float32 in the red component.
342 union isl_color_value fast_clear_color
;
345 * For external surfaces, this is DRM format modifier that was used to
346 * create or import the surface. For internal surfaces, this will always
347 * be DRM_FORMAT_MOD_INVALID.
349 uint64_t drm_modifier
;
351 /* These are also refcounted:
357 intel_miptree_alloc_aux(struct brw_context
*brw
,
358 struct intel_mipmap_tree
*mt
);
360 enum intel_miptree_create_flags
{
361 /** No miptree create flags */
362 MIPTREE_CREATE_DEFAULT
= 0,
364 /** Miptree creation should try to allocate a currently busy BO
366 * This may be advantageous if we know the next thing to touch the BO will
367 * be the GPU because the BO will likely already be in the GTT and maybe
368 * even in some caches. If there is a chance that the next thing to touch
369 * the miptree BO will be the CPU, this flag should not be set.
371 MIPTREE_CREATE_BUSY
= 1 << 0,
373 /** Create the miptree with auxiliary compression disabled
375 * This does not prevent the caller of intel_miptree_create from coming
376 * along later and turning auxiliary compression back on but it does mean
377 * that the miptree will be created with mt->aux_usage == NONE.
379 MIPTREE_CREATE_NO_AUX
= 1 << 1,
382 struct intel_mipmap_tree
*intel_miptree_create(struct brw_context
*brw
,
391 enum intel_miptree_create_flags flags
);
393 struct intel_mipmap_tree
*
394 intel_miptree_create_for_bo(struct brw_context
*brw
,
402 enum isl_tiling tiling
,
403 enum intel_miptree_create_flags flags
);
405 struct intel_mipmap_tree
*
406 intel_miptree_create_for_dri_image(struct brw_context
*brw
,
410 bool allow_internal_aux
);
413 intel_update_winsys_renderbuffer_miptree(struct brw_context
*intel
,
414 struct intel_renderbuffer
*irb
,
415 struct intel_mipmap_tree
*singlesample_mt
,
416 uint32_t width
, uint32_t height
,
420 * Create a miptree appropriate as the storage for a non-texture renderbuffer.
421 * The miptree has the following properties:
422 * - The target is GL_TEXTURE_2D.
423 * - There are no levels other than the base level 0.
426 struct intel_mipmap_tree
*
427 intel_miptree_create_for_renderbuffer(struct brw_context
*brw
,
431 uint32_t num_samples
);
434 intel_depth_format_for_depthstencil_format(mesa_format format
);
437 intel_lower_compressed_format(struct brw_context
*brw
, mesa_format format
);
440 brw_get_num_logical_layers(const struct intel_mipmap_tree
*mt
, unsigned level
);
442 /** \brief Assert that the level and layer are valid for the miptree. */
444 intel_miptree_check_level_layer(const struct intel_mipmap_tree
*mt
,
448 void intel_miptree_reference(struct intel_mipmap_tree
**dst
,
449 struct intel_mipmap_tree
*src
);
451 void intel_miptree_release(struct intel_mipmap_tree
**mt
);
453 /* Check if an image fits an existing mipmap tree layout
455 bool intel_miptree_match_image(struct intel_mipmap_tree
*mt
,
456 struct gl_texture_image
*image
);
459 intel_miptree_get_image_offset(const struct intel_mipmap_tree
*mt
,
460 GLuint level
, GLuint slice
,
461 GLuint
*x
, GLuint
*y
);
464 get_isl_surf_dim(GLenum target
);
467 get_isl_dim_layout(const struct gen_device_info
*devinfo
,
468 enum isl_tiling tiling
, GLenum target
);
471 intel_get_image_dims(struct gl_texture_image
*image
,
472 int *width
, int *height
, int *depth
);
475 intel_get_tile_masks(enum isl_tiling tiling
, uint32_t cpp
,
476 uint32_t *mask_x
, uint32_t *mask_y
);
479 intel_get_tile_dims(enum isl_tiling tiling
, uint32_t cpp
,
480 uint32_t *tile_w
, uint32_t *tile_h
);
483 intel_miptree_get_tile_offsets(const struct intel_mipmap_tree
*mt
,
484 GLuint level
, GLuint slice
,
488 intel_miptree_get_aligned_offset(const struct intel_mipmap_tree
*mt
,
489 uint32_t x
, uint32_t y
);
492 intel_miptree_copy_slice(struct brw_context
*brw
,
493 struct intel_mipmap_tree
*src_mt
,
494 unsigned src_level
, unsigned src_layer
,
495 struct intel_mipmap_tree
*dst_mt
,
496 unsigned dst_level
, unsigned dst_layer
);
499 intel_miptree_copy_teximage(struct brw_context
*brw
,
500 struct intel_texture_image
*intelImage
,
501 struct intel_mipmap_tree
*dst_mt
);
504 * \name Miptree HiZ functions
507 * It is safe to call the "slice_set_need_resolve" and "slice_resolve"
508 * functions on a miptree without HiZ. In that case, each function is a no-op.
512 intel_miptree_level_has_hiz(const struct intel_mipmap_tree
*mt
, uint32_t level
);
517 intel_miptree_has_color_unresolved(const struct intel_mipmap_tree
*mt
,
518 unsigned start_level
, unsigned num_levels
,
519 unsigned start_layer
, unsigned num_layers
);
522 #define INTEL_REMAINING_LAYERS UINT32_MAX
523 #define INTEL_REMAINING_LEVELS UINT32_MAX
525 /** Prepare a miptree for access
527 * This function should be called prior to any access to miptree in order to
528 * perform any needed resolves.
530 * \param[in] start_level The first mip level to be accessed
532 * \param[in] num_levels The number of miplevels to be accessed or
533 * INTEL_REMAINING_LEVELS to indicate every level
534 * above start_level will be accessed
536 * \param[in] start_layer The first array slice or 3D layer to be accessed
538 * \param[in] num_layers The number of array slices or 3D layers be
539 * accessed or INTEL_REMAINING_LAYERS to indicate
540 * every layer above start_layer will be accessed
542 * \param[in] aux_supported Whether or not the access will support the
543 * miptree's auxiliary compression format; this
544 * must be false for uncompressed miptrees
546 * \param[in] fast_clear_supported Whether or not the access will support
547 * fast clears in the miptree's auxiliary
551 intel_miptree_prepare_access(struct brw_context
*brw
,
552 struct intel_mipmap_tree
*mt
,
553 uint32_t start_level
, uint32_t num_levels
,
554 uint32_t start_layer
, uint32_t num_layers
,
555 enum isl_aux_usage aux_usage
,
556 bool fast_clear_supported
);
558 /** Complete a write operation
560 * This function should be called after any operation writes to a miptree.
561 * This will update the miptree's compression state so that future resolves
562 * happen correctly. Technically, this function can be called before the
563 * write occurs but the caller must ensure that they don't interlace
564 * intel_miptree_prepare_access and intel_miptree_finish_write calls to
565 * overlapping layer/level ranges.
567 * \param[in] level The mip level that was written
569 * \param[in] start_layer The first array slice or 3D layer written
571 * \param[in] num_layers The number of array slices or 3D layers
572 * written or INTEL_REMAINING_LAYERS to indicate
573 * every layer above start_layer was written
575 * \param[in] written_with_aux Whether or not the write was done with
576 * auxiliary compression enabled
579 intel_miptree_finish_write(struct brw_context
*brw
,
580 struct intel_mipmap_tree
*mt
, uint32_t level
,
581 uint32_t start_layer
, uint32_t num_layers
,
582 enum isl_aux_usage aux_usage
);
584 /** Get the auxiliary compression state of a miptree slice */
586 intel_miptree_get_aux_state(const struct intel_mipmap_tree
*mt
,
587 uint32_t level
, uint32_t layer
);
589 /** Set the auxiliary compression state of a miptree slice range
591 * This function directly sets the auxiliary compression state of a slice
592 * range of a miptree. It only modifies data structures and does not do any
593 * resolves. This should only be called by code which directly performs
594 * compression operations such as fast clears and resolves. Most code should
595 * use intel_miptree_prepare_access or intel_miptree_finish_write.
598 intel_miptree_set_aux_state(struct brw_context
*brw
,
599 struct intel_mipmap_tree
*mt
, uint32_t level
,
600 uint32_t start_layer
, uint32_t num_layers
,
601 enum isl_aux_state aux_state
);
604 * Prepare a miptree for raw access
606 * This helper prepares the miptree for access that knows nothing about any
607 * sort of compression whatsoever. This is useful when mapping the surface or
608 * using it with the blitter.
611 intel_miptree_access_raw(struct brw_context
*brw
,
612 struct intel_mipmap_tree
*mt
,
613 uint32_t level
, uint32_t layer
,
616 intel_miptree_prepare_access(brw
, mt
, level
, 1, layer
, 1,
617 ISL_AUX_USAGE_NONE
, false);
619 intel_miptree_finish_write(brw
, mt
, level
, layer
, 1, ISL_AUX_USAGE_NONE
);
623 intel_miptree_texture_aux_usage(struct brw_context
*brw
,
624 struct intel_mipmap_tree
*mt
,
625 enum isl_format view_format
,
626 enum gen9_astc5x5_wa_tex_type astc5x5_wa_bits
);
628 intel_miptree_prepare_texture(struct brw_context
*brw
,
629 struct intel_mipmap_tree
*mt
,
630 enum isl_format view_format
,
631 uint32_t start_level
, uint32_t num_levels
,
632 uint32_t start_layer
, uint32_t num_layers
,
633 enum gen9_astc5x5_wa_tex_type astc5x5_wa_bits
);
635 intel_miptree_prepare_image(struct brw_context
*brw
,
636 struct intel_mipmap_tree
*mt
);
639 intel_miptree_render_aux_usage(struct brw_context
*brw
,
640 struct intel_mipmap_tree
*mt
,
641 enum isl_format render_format
,
643 bool draw_aux_disabled
);
645 intel_miptree_prepare_render(struct brw_context
*brw
,
646 struct intel_mipmap_tree
*mt
, uint32_t level
,
647 uint32_t start_layer
, uint32_t layer_count
,
648 enum isl_aux_usage aux_usage
);
650 intel_miptree_finish_render(struct brw_context
*brw
,
651 struct intel_mipmap_tree
*mt
, uint32_t level
,
652 uint32_t start_layer
, uint32_t layer_count
,
653 enum isl_aux_usage aux_usage
);
655 intel_miptree_prepare_depth(struct brw_context
*brw
,
656 struct intel_mipmap_tree
*mt
, uint32_t level
,
657 uint32_t start_layer
, uint32_t layer_count
);
659 intel_miptree_finish_depth(struct brw_context
*brw
,
660 struct intel_mipmap_tree
*mt
, uint32_t level
,
661 uint32_t start_layer
, uint32_t layer_count
,
664 intel_miptree_prepare_external(struct brw_context
*brw
,
665 struct intel_mipmap_tree
*mt
);
667 intel_miptree_finish_external(struct brw_context
*brw
,
668 struct intel_mipmap_tree
*mt
);
671 intel_miptree_make_shareable(struct brw_context
*brw
,
672 struct intel_mipmap_tree
*mt
);
675 intel_miptree_updownsample(struct brw_context
*brw
,
676 struct intel_mipmap_tree
*src
,
677 struct intel_mipmap_tree
*dst
);
680 intel_update_r8stencil(struct brw_context
*brw
,
681 struct intel_mipmap_tree
*mt
);
684 intel_miptree_map(struct brw_context
*brw
,
685 struct intel_mipmap_tree
*mt
,
694 ptrdiff_t *out_stride
);
697 intel_miptree_unmap(struct brw_context
*brw
,
698 struct intel_mipmap_tree
*mt
,
703 intel_miptree_sample_with_hiz(struct brw_context
*brw
,
704 struct intel_mipmap_tree
*mt
);
707 intel_miptree_set_clear_color(struct brw_context
*brw
,
708 struct intel_mipmap_tree
*mt
,
709 union isl_color_value clear_color
);
711 /* Get a clear color suitable for filling out an ISL surface state. */
712 union isl_color_value
713 intel_miptree_get_clear_color(const struct gen_device_info
*devinfo
,
714 const struct intel_mipmap_tree
*mt
,
715 enum isl_format view_format
, bool sampling
,
716 struct brw_bo
**clear_color_bo
,
717 uint64_t *clear_color_offset
);
721 intel_miptree_blt_pitch(struct intel_mipmap_tree
*mt
)
723 int pitch
= mt
->surf
.row_pitch_B
;
724 if (mt
->surf
.tiling
!= ISL_TILING_LINEAR
)
730 intel_miptree_get_memcpy_type(mesa_format tiledFormat
, GLenum format
, GLenum type
,