1Name 2 3 EXT_unpack_subimage 4 5Name Strings 6 7 GL_EXT_unpack_subimage 8 9Contact 10 11 Peter Pipkorn, NVIDIA Corporation (ppipkorn 'at' nvidia.com) 12 13Contributors 14 15 Daniel Kartch, NVIDIA Corporation (dkartch 'at' nvidia.com) 16 Nicolai de Haan, NVIDIA Corporation (nicolaid 'at' nvidia.com) 17 Daniel Koch, NVIDIA Corporation (dkoch 'at' nvidia.com) 18 19Status 20 21 Complete. 22 23Version 24 25 Last Modifed Date: Feb 8, 2013 26 Author Revision: 2 27 28Number 29 30 OpenGL ES Extension #90 31 32Dependencies 33 34 The extension is written against the OpenGL ES 2.0 specification. 35 The extension references the OpenGL 2.0 specification. 36 37Overview 38 39 This OpenGL ES 2.0 extension adds support for GL_UNPACK_ROW_LENGTH, 40 GL_UNPACK_SKIP_ROWS and GL_UNPACK_SKIP_PIXELS as valid enums to 41 PixelStore. The functionality is the same as in OpenGL. These are 42 useful for updating textures with a sub-rectangle of pixel data 43 coming from a larger image in host memory. 44 45IP Status 46 47 None 48 49New Procedures and Functions 50 51 None 52 53New Tokens 54 55 Accepted by the <pname> parameters of PixelStorei, GetIntegerv, and 56 GetFloatv: 57 58 GL_UNPACK_ROW_LENGTH_EXT 0x0CF2 59 GL_UNPACK_SKIP_ROWS_EXT 0x0CF3 60 GL_UNPACK_SKIP_PIXELS_EXT 0x0CF4 61 62Additions to the OpenGL ES 2.0 Specification 63 64 Modifications to Table 3.1 (PixelStore parameters) 65 66 Add the following entries: 67 68 Parameter Name Type Initial Value Valid Range 69 ============== ==== ============= =========== 70 UNPACK_ROW_LENGTH_EXT integer 0 [0,Infinity) 71 UNPACK_SKIP_ROWS_EXT integer 0 [0,Infinity) 72 UNPACK_SKIP_PIXELS_EXT integer 0 [0,Infinity) 73 74 Modifications to 3.6.2 Transfer of Pixel Rectangles, in the Unpacking 75 section: 76 77 Change 78 79 "The number of groups in a row is width;" 80 81 to 82 83 "If the value of UNPACK_ROW_LENGTH_EXT is not positive, then the 84 number of groups in a row is <width>; otherwise the number of 85 groups is UNPACK_ROW_LENGTH_EXT." 86 87 After the sentence 88 89 "If the number of bits per element is not 1, 2, 4 or 8 times 90 the number of bits in a GL ubyte, then k = nl for all values 91 of a." 92 93 insert: 94 95 "There is a mechanism for selecting a sub-rectangle of groups 96 from a larger containing rectangle. This mechanism relies on 97 three integer parameters: UNPACK_ROW_LENGTH_EXT, UNPACK_SKIP_ROWS_EXT, 98 and UNPACK_SKIP_PIXELS_EXT. Before obtaining the first group from 99 memory, the pointer supplied to TexImage2D is effectively 100 advanced by (UNPACK_SKIP_PIXELS_EXT)n + (UNPACK_SKIP_ROWS_EXT)k 101 elements. Then <width> groups are obtained from contiguous 102 elements in memory (without advancing the pointer), after 103 which the pointer is advanced by k elements. <height> sets of 104 <width> groups of values are obtained this way. See figure 105 3.6." 106 107 Before Table 3.5 Packed pixel formats, insert 108 109 Figure 3.8 from the OpenGL 2.0 specification (a visual 110 description of UNPACK_ROW_LENGTH_EXT, UNPACK_SKIP_ROWS_EXT, and 111 UNPACK_SKIP_PIXELS_EXT) 112 113Errors 114 115 None 116 117New State 118 119 Modifications to Table 6.12 Pixels in section 6.2 State Tables: 120 121 Get Value Type Get Cmnd Initial Description Sec. 122 Value 123 ==================== ==== =========== ======= =============================== ===== 124 UNPACK_ROW_LENGTH_EXT Z+ GetIntegerv 0 Value of UNPACK_ROW_LENGTH_EXT 3.6.1 125 UNPACK_SKIP_ROWS_EXT Z+ GetIntegerv 0 Value of UNPACK_SKIP_ROWS_EXT 3.6.1 126 UNPACK_SKIP_PIXELS_EXT Z+ GetIntegerv 0 Value of UNPACK_SKIP_PIXELS_EXT 3.6.1 127 128Issues 129 130 1. Can't this be done with repeated calls to 131 TexSubImage2D/TexSubImage3D? 132 133 Yes, it is possible to unpack pixels from a sub-rectangle in 134 host memory by by calling these functions for one line at a 135 time, but this could add unnecessary burden on the CPU system. 136 Specifying GL_UNPACK_ROW_LENGTH_EXT makes it possible to unpack 137 sub-rectangles of pixels with lower overhead. 138 139 2. Should the corresponding PACK enums be added? 140 141 No, it should be done in a separate extension. There is no 142 dependency between the PACK enums and the UNPACK enums. 143 144 3. Are these UNPACK_SKIP_* tokens strictly necessary? 145 146 No. The same functionality can be achieved by advancing the 147 pixel pointer to host memory appropriately before issuing an 148 unpacking function call. They are included here for both 149 completeness and for convenience. 150 151 4. Should the new tokens be suffixed? 152 153 Yes. This extension was originally drafted with unsuffixed tokens 154 since they provide the same functionality as in core Desktop GL. 155 However, the policy of the ES working group is that suffixes 156 must be used in extensions even for functionality that is core 157 in Desktop GL. 158 159Revision History 160 161 Rev. Date Author Changes 162 ---- -------- --------- ------------------------------------ 163 1 03/25/11 ppipkorn First revision. 164 2 02/08/13 dgkoch add suffixes to tokens 165 remove unnecessary column from table 6.12 edits 166