docs/MESA_packed_depth_stencil.spec

   1 XXX - Not complete yet!!!
   2
   3 Name
   4
   5     MESA_packed_depth_stencil
   6
   7 Name Strings
   8
   9     GL_MESA_packed_depth_stencil
  10
  11 Contact
  12
  13     Keith Whitwell, VA Linux Systems Inc. (keithw 'at' valinux.com)
  14     Brian Paul, VA Linux Systems Inc. (brianp 'at' valinux.com)
  15
  16 Status
  17
  18     Not yet shipping.
  19
  20 Version
  21
  22     $Id: MESA_packed_depth_stencil.spec,v 1.1 2000/11/03 14:58:45 brianp Exp $
  23
  24 Number
  25
  26     ???
  27
  28 Dependencies
  29
  30     EXT_abgr affects the definition of this extension
  31     SGIS_texture4D affects the definition of this extension
  32     EXT_cmyka affects the definition of this extension
  33     ARB_packed_pixels affects the definition of this extension
  34
  35 Overview
  36
  37     Provides a mechanism for DrawPixels and ReadPixels to efficiently
  38     transfer depth and stencil image data.  Specifically, we defined new
  39     packed pixel formats and types which pack both stencil and depth
  40     into one value.
  41
  42 Issues:
  43
  44     1. Is this the right way to distinguish between 24/8 and 8/24
  45        pixel formats?  Should we instead provide both:
  46
  47        GL_DEPTH_STENCIL_MESA
  48        GL_STENCIL_DEPTH_MESA
  49
  50        And perhaps just use GL_UNSIGNED_INT, GL_UNSIGNED_SHORT ?
  51
  52     2. If not, is it correct to use _REV to indicate that stencil
  53        preceeds depth in the 1_15 and 8_24 formats?
  54
  55     3. Do we really want the GL_UNSIGNED_SHORT formats?
  56
  57
  58 New Procedures and Functions
  59
  60     None.
  61
  62 New Tokens
  63
  64     Accepted by the <format> parameter of ReadPixels and DrawPixels:
  65
  66         GL_DEPTH_STENCIL_MESA           0x8750
  67
  68     Accepted by the <type> parameter of ReadPixels and DrawPixels:
  69
  70         GL_UNSIGNED_INT_24_8_MESA       0x8751
  71         GL_UNSIGNED_INT_8_24_REV_MESA   0x8752
  72         GL_UNSIGNED_SHORT_15_1_MESA     0x8753
  73         GL_UNSIGNED_SHORT_1_15_REV_MESA 0x8754
  74
  75 Additions to Chapter 2 of the 1.1 Specification (OpenGL Operation)
  76
  77     None
  78
  79 Additions to Chapter 3 of the 1.1 Specification (Rasterization)
  80
  81     One entry is added to table 3.5 (DrawPixels and ReadPixels formats).
  82     The new table is:
  83
  84                         Target
  85         Format Name     Buffer  Element Meaning and Order
  86         -----------     ------  -------------------------
  87         COLOR_INDEX     Color   Color index
  88         STENCIL_INDEX   Stencil Stencil index
  89         DEPTH_COMPONENT Depth   Depth component
  90         RED             Color   R component
  91         GREEN           Color   G component
  92         BLUE            Color   B component
  93         ALPHA           Color   A component
  94         RGB             Color   R, G, B components
  95         RGBA            Color   R, G, B, A components
  96         BGRA            Color   B, G, R, A components
  97         ABGR_EXT        Color   A, B, G, R components
  98         CMYK_EXT        Color   Cyan, Magenta, Yellow, Black components
  99         CMYKA_EXT       Color   Cyan, Magenta, Yellow, Black, A components
 100         LUMINANCE       Color   Luminance component
 101         LUMINANCE_ALPHA Color   Luminance, A components
 102         DEPTH_STENCIL   Depth,  Depth component, stencil index.
 103                         Stencil
 104
 105         Table 3.5: DrawPixels and ReadPixels formats.  The third column
 106         gives a description of and the number and order of elements in a
 107         group.
 108
 109     Add to the description of packed pixel formats:
 110
 111         <type> Parameter                Data    of        Matching
 112         Token Name                      Type    Elements  Pixel Formats
 113         ----------------                ----    --------  -------------
 114
 115         UNSIGNED_BYTE_3_3_2           ubyte   3       RGB
 116         UNSIGNED_BYTE_2_3_3_REV       ubyte   3       RGB
 117         UNSIGNED_SHORT_5_6_5          ushort  3       RGB
 118         UNSIGNED_SHORT_5_6_5_REV      ushort  3       RGB
 119         UNSIGNED_SHORT_4_4_4_4        ushort  4       RGBA,BGRA,ABGR_EXT,CMYK_EXT
 120         UNSIGNED_SHORT_4_4_4_4_REV    ushort  4       RGBA,BGRA
 121         UNSIGNED_SHORT_5_5_5_1        ushort  4       RGBA,BGRA,ABGR_EXT,CMYK_EXT
 122         UNSIGNED_SHORT_1_5_5_5_REV    ushort  4       RGBA,BGRA
 123         UNSIGNED_INT_8_8_8_8          uint    4       RGBA,BGRA,ABGR_EXT,CMYK_EXT
 124         UNSIGNED_INT_8_8_8_8_REV      uint    4       RGBA,BGRA
 125         UNSIGNED_INT_10_10_10_2       uint    4       RGBA,BGRA,ABGR_EXT,CMYK_EXT
 126         UNSIGNED_INT_2_10_10_10_REV   uint    4       RGBA,BGRA
 127         UNSIGNED_SHORT_15_1_MESA      ushort  2       DEPTH_STENCIL_MESA
 128         UNSIGNED_SHORT_1_15_REV_MESA  ushort  2       DEPTH_STENCIL_MESA
 129         UNSIGNED_SHORT_24_8_MESA      ushort  2       DEPTH_STENCIL_MESA
 130         UNSIGNED_SHORT_8_24_REV_MESA  ushort  2       DEPTH_STENCIL_MESA
 131
 132         UNSIGNED_INT_8_24:
 133
 134              31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
 135             +-----------------------+-----------------------------------------------------------------------+
 136             |                       |                                                                       |
 137             +-----------------------+-----------------------------------------------------------------------+
 138
 139                     first                                       second
 140                     element                                     element
 141
 142
 143         UNSIGNED_INT_24_8:
 144
 145              31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10  9  8  7  6  5  4  3  2  1  0
 146             +----------------------------------------------------------------------+------------------------+
 147             |                                                                      |                        |
 148             +----------------------------------------------------------------------+------------------------+
 149
 150                     first                                                                 second
 151                     element                                                               element
 152
 153         UNSIGNED_SHORT_15_1:
 154
 155               15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
 156             +-----------------------------------------------------------+---+
 157             |                                                           |   |
 158             +-----------------------------------------------------------+---+
 159
 160                         first                                           second
 161                         element                                         element
 162
 163
 164         UNSIGNED_SHORT_1_15_REV:
 165
 166               15  14  13  12  11  10  9   8   7   6   5   4   3   2   1   0
 167             +---+-----------------------------------------------------------+
 168             |   |                                                           |
 169             +---+-----------------------------------------------------------+
 170
 171             second                  first
 172             element                 element
 173
 174     The assignment of elements to fields in the packed pixel is as
 175     described in the table below:
 176
 177                            First       Second   Third       Fourth
 178         Format             Element     Element  Element     Element
 179         ------             -------     -------  -------     -------
 180         RGB                red         green    blue
 181         RGBA               red         green    blue        alpha
 182         BGRA               blue        green    red         alpha
 183         ABGR_EXT           alpha       blue     green       red
 184         CMYK_EXT           cyan        magenta  yellow      black
 185         DEPTH_STENCIL_MESA depth       stencil
 186
 187 Additions to Chapter 4 of the 1.1 Specification (Per-Fragment Operations
 188 and the Frame Buffer)
 189
 190     The new format is added to the discussion of Obtaining Pixels from the
 191     Framebuffer.  It should read " If the <format> is one of RED, GREEN,
 192     BLUE, ALPHA, RGB, RGBA, ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, and
 193     the GL is in color index mode, then the color index is obtained."
 194
 195     The new format is added to the discussion of Index Lookup.  It should
 196     read "If <format> is one of RED, GREEN, BLUE, ALPHA, RGB, RGBA,
 197     ABGR_EXT, LUMINANCE, or LUMINANCE_ALPHA, then the index is used to
 198     reference 4 tables of color components: PIXEL_MAP_I_TO_R,
 199     PIXEL_MAP_I_TO_G, PIXEL_MAP_I_TO_B, and PIXEL_MAP_I_TO_A."
 200
 201
 202 Additions to Chapter 5 of the 1.1 Specification (Special Functions)
 203
 204     None
 205
 206 Additions to Chapter 6 of the 1.1 Specification (State and State Requests)
 207
 208     None
 209
 210 Additions to the GLX Specification
 211
 212     None
 213
 214 GLX Protocol
 215
 216     TBD
 217
 218 Errors
 219
 220     None
 221
 222 New State
 223
 224     None
 225
 226 Revision History
 227
 228     Version 1.0 - 23 Sep 2000
 229         Keith's original version.
 230
 231     Version 1.1 - 3 Nov 2000
 232         Brian's edits, assigned values to new enums.
 233