glPixelStore(3G)
glPixelStoref, glPixelStorei - set pixel storage modes
As shipped in IRIX 6.5.5. Unchanged since IRIX 6.5.
NAME glPixelStoref, glPixelStorei - set pixel storage modes C SPECIFICATION void glPixelStoref( GLenum pname, GLfloat param ) void glPixelStorei( GLenum pname, GLint param ) PARAMETERS pname Specifies the symbolic name of the parameter to be set. Ten values affect the packing of pixel data into client memory: GL_PACK_SWAP_BYTES, GL_PACK_LSB_FIRST, GL_PACK_ROW_LENGTH, GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, GL_PACK_ALIGNMENT, GL_PACK_IMAGE_HEIGHT_EXT, GL_PACK_IMAGE_DEPTH_SGIS, GL_PACK_SKIP_IMAGES_EXT, and GL_PACK_SKIP_VOLUMES_SGIS. Ten more affect the unpacking of pixel data from client memory: GL_UNPACK_SWAP_BYTES, GL_UNPACK_LSB_FIRST, GL_UNPACK_ROW_LENGTH, GL_UNPACK_SKIP_PIXELS, GL_UNPACK_SKIP_ROWS, GL_UNPACK_ALIGNMENT, GL_UNPACK_IMAGE_HEIGHT_EXT, GL_UNPACK_IMAGE_DEPTH_SGIS, GL_UNPACK_SKIP_IMAGES_EXT, and GL_UNPACK_SKIP_VOLUMES_SGIS. param Specifies the value that pname is set to. DESCRIPTION glPixelStore sets pixel storage modes that affect the operation of subsequent commands which unpack pixel data from client memory and which pack pixel data into client memory. Pixel data is unpacked from client memory during glDrawPixels commands and when specifying bitmaps (see glBitmap), polygon stipple patterns (see glPolygonStipple), color tables (see glColorTableSGI), convolution filters (see glConvolutionFilter1DEXT, glConvolutionFilter2DEXT, and glSeparableFilter2DEXT), and texture patterns (see glTexImage1D, glTexSubImage1DEXT, glTexImage2D, glTexSubImage2DEXT, glTexImage3DEXT, glTexSubImage3DEXT, glTexImage4DSGIS, and glTexSubImage4DSGIS). Pixel data is packed into client memory during glReadPixels commands and when querying polygon stipple patterns (see glGetPolygonStipple), color tables (see glGetColorTableSGI), convolution filters (see glGetConvolutionFilterEXT and glGetSeparableFilterEXT), texture patterns (see glGetTexImage), histogram results (see glGetHistogramEXT), and minmax results (see glGetMinmaxEXT); When pixel data is unpacked from client memory, the interpretation of the data in memory is controlled by the unpack parameters to glPixelStore and by the type, format, and size arguments to the pixel command (for example, by the width and height parameters to glDrawPixels). The pixel format specifies that each pixel consists of either a single index value, a single depth component, or one, two, three or four color components. Unless packed pixel formats are used, the type argument to the command specifies that the elements of a pixel are to be read from memory as a sequence of signed or unsigned bytes, shorts, or integers, or single- precision floating-point values. Packed pixel types allow all the elements of each pixel to be read from a single unsigned byte, unsigned short, or unsigned int. (See glDrawPixels for more information.) In the case of glBitmap and glPolygonStipple, the pixel format is inferred to be GL_COLOR_INDEX and the type is inferred to be GL_BITMAP. When commands which pack data into client memory (for example, glReadPixels or glGetTexImage) are called, pixels are written into client memory as specified by the unpack state specified by glPixelStore and by the type, format, and size arguments to the command. In a manner similar to that of glDrawPixels, the pixel format determines the components of each pixel and the pixel type indicates the data type and whether or not the pixels are packed into memory. (See glReadPixels for more information.) In the case of glGetPolygonStipple the pixel format is inferred to be GL_COLOR_INDEX and the type is inferred to be GL_BITMAP. pname is a symbolic constant indicating the parameter to be set, and param is the new value. The parameters GL_PACK_LSB_FIRST, GL_UNPACK_LSB_FIRST, GL_PACK_SWAP_BYTES, and GL_UNPACK_SWAP_BYTES specify the arrangement of bits within bytes or bytes within words of an image. These parameters are described in detail below. The other parameters are typically used when a subregion of a larger image in client memory is being written or read by the GL. The parameters GL_PACK_ROW_LENGTH, GL_UNPACK_ROW_LENGTH, GL_PACK_IMAGE_HEIGHT_EXT, GL_UNPACK_IMAGE_HEIGHT_EXT, GL_PACK_IMAGE_DEPTH_SGIS, and GL_UNPACK_IMAGE_DEPTH_SGIS are used specify the dimensions of the entire client image. GL_PACK_ALIGNMENT and GL_UNPACK_ALIGNMENT are used to specify the alignment in memory of the start of each row of the client image. GL_PACK_SKIP_PIXELS, GL_UNPACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, GL_UNPACK_SKIP_ROWS, GL_PACK_SKIP_IMAGES_EXT, GL_UNPACK_SKIP_IMAGES_EXT, GL_PACK_SKIP_VOLUMES_SGIS, and GL_UNPACK_SKIP_VOLUMES_SGIS are used to specify the location of the subregion which is to be read or written by subsequent GL commands. These offsets describe the lower left corner of the first image of the first volume. The size of the subregion is specified by arguments to the GL command which will transfer the pixels. A pointer passed into the routine (referred to in this document as p) gives the location in client memory of the lower left corner of the large image. More detailed and rigorous descriptions of each parameter may be found below. Note that specifying a subregion of a larger image is a common use of these parameters, but they are often useful in other situations. For example, GL_PACK_ROW_LENGTH may be set to twice the width of the image to select every other line of an image in an application using interlacing. Ten of the twenty storage parameters affect how pixel data is returned to client memory, and are therefore significant for glReadPixels, glGetTexImage, glGetColorTableSGI, glGetConvolutionFilterEXT, glGetPolygonStipple, glGetSeparableFilterEXT, glGetHistogramEXT, and glGetMinmaxEXT commands. These parameters are as follows: GL_PACK_SWAP_BYTES If true, byte swapping is performed as the data is written to client memory. For pixels that aren't packed, byte ordering for multibyte color components, depth components, color indices, or stencil indices is reversed. That is, if a four- byte component is made up of bytes b , b , b , b , it is stored 0 1 2 3 in memory as b , b , b , b . In the case of the packed pixel 3 2 1 0 types, byte swapping is performed before the elements are extracted from each pixel. GL_PACK_LSB_FIRST If true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. This parameter is significant for bitmap data only. GL_PACK_ROW_LENGTH If greater than zero, GL_PACK_ROW_LENGTH defines the number of pixels in a row. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping i = a * ceiling(s*w / a) bytes, where s is the size in bytes of a pixel (equal to the number of components in a pixel multiplied by the size in bytes of a component for non-packed pixel types, or to the size in bytes of a complete pixel for packed pixel types), w is the number of pixels in a row (as specified with GL_PACK_ROW_LENGTH if it is greater than zero, the width argument to the pixel routine otherwise), and a is the value of GL_PACK_ALIGNMENT. If a<s, then it is as if a=s. In the case of 1-bit values, the location of the next row is obtained by skipping i = 8 * a * ceiling(s*w / 8*a) bytes. The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue. GL_PACK_IMAGE_HEIGHT_EXT If greater than zero, GL_PACK_IMAGE_HEIGHT_EXT defines the number of rows in an image. If the first pixel of an image is placed at location p in memory, then the location of the first pixel of the next image is obtained by skipping j=ih elements, where i is the offset from the beginning of one row in an image to the beginning of the next row in the image (as described in the GL_PACK_ROW_LENGTH section) and h is the height of the image. h is equal the value specified with GL_PACK_IMAGE_HEIGHT_EXT if this value is greater than zero and is equal to the height argument to the pixel routine otherwise. If the routine has no height argument and the height was not specified with GL_PACK_IMAGE_HEIGHT_EXT (or was specified as zero), h is the height of the data to be returned. GL_PACK_IMAGE_DEPTH_SGIS If greater than zero, GL_PACK_IMAGE_DEPTH_SGIS defines the number of images in a volume. If the first pixel of a volume is placed at location p in memory, then the location of the first pixel of the next volume is obtained by skipping k=jd bytes, where j is the offset from the beginning of one image to the beginning of the next image (as described in the GL_PACK_IMAGE_HEIGHT_EXT section) and d is the depth of the image. d is equal to the value specified with GL_PACK_IMAGE_DEPTH_SGIS if this value is greater than zero and is equal to the depth argument to the pixel routine otherwise. If the routine has no depth argument and the depth was not specified with GL_PACK_IMAGE_DEPTH_SGIS (or was specified as zero), d is the depth of the data to be returned. GL_PACK_SKIP_PIXELS and GL_PACK_SKIP_ROWS These values are provided mainly as a convenience to the programmer; except when 1-bit per pixel data is being returned, they provide no functionality that cannot be duplicated simply by incrementing the pointer passed to the command which is writing pixel data to client memory. For multi-bit data types, setting GL_PACK_SKIP_PIXELS to l is equivalent to incrementing the pointer just once by sl bytes, where s is the number of bytes in each pixel (as described above in the GL_PACK_ROW_LENGTH section). Setting GL_PACK_SKIP_ROWS to m is equivalent to incrementing the pointer just once by im bytes, where i is the number of bytes per row, as computed above in the GL_PACK_ROW_LENGTH section. When 1-bit (GL_BITMAP) data is being written to client memory, setting GL_PACK_SKIP_PIXELS to l is equivalent to incrementing the pointer just once by floor(l/8) bytes. For each row of the image, the data returned will begin at bit l%8 of the byte, where 0 is the most significant bit. Other bits will be left unchanged. Note that the adjustment to the pointer takes place just once, before the start of the pixel transfer; specifying a value of one for GL_PACK_SKIP_ROWS does not cause every other row of the image to be skipped. GL_PACK_SKIP_IMAGES_EXT Setting GL_PACK_SKIP_IMAGES_EXT to n is equivalent to incrementing the pointer passed to the command just once by jn bytes, where j is the number of bytes per image, as computed above in the GL_PACK_IMAGE_HEIGHT_EXT section. The offset specified by GL_PACK_SKIP_IMAGES_EXT is applied only to data of three or more dimensions. The offset is applied in addition to the offsets specified by GL_PACK_SKIP_PIXELS and GL_PACK_SKIP_ROWS as described above. GL_PACK_SKIP_VOLUMES_SGIS Setting GL_PACK_SKIP_VOLUMES_SGIS to o is equivalent to incrementing the pointer passed to the command just once by ko bytes, where k is the number of bytes per volume, as computed in the GL_PACK_IMAGE_DEPTH_SGIS section. The offset specified by GL_PACK_SKIP_VOLUMES_SGIS is applied only to data of four or more dimensions. GL_PACK_ALIGNMENT Specifies the alignment requirements for the start of each pixel row in memory. The allowable values are 1 (byte- alignment), 2 (rows aligned to even-numbered bytes), 4 (word alignment), and 8 (rows start on double-word boundaries). The other ten of the twenty storage parameters affect how pixel data is read from client memory. They are as follows: GL_UNPACK_SWAP_BYTES If true, byte ordering for multibyte color components, depth components, color indices, or stencil indices is reversed. That is, if a four-byte component is made up of bytes b , b , b , b , it is 0 1 2 3 taken from memory as b , b , b , b if GL_UNPACK_SWAP_BYTES is true. 3 2 1 0 GL_UNPACK_SWAP_BYTES has no effect on the memory order of components within a pixel, only on the order of bytes within components or indices. For example, the three components of a GL_RGB format pixel are always stored with red first, green second, and blue third, regardless of the value of GL_UNPACK_SWAP_BYTES. GL_UNPACK_LSB_FIRST If true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. This is significant for bitmap data only. GL_UNPACK_ROW_LENGTH If greater than zero, GL_UNPACK_ROW_LENGTH defines the number of pixels in a row. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping i = a * ceiling(s*w / a) bytes, where s is the size in bytes of a pixel (equal to the number of components in a pixel multiplied by the size in bytes of a component for non-packed pixel types, or to the size in bytes of a complete pixel for packed pixel types), w is the number of pixels in a row (as specified with GL_UNPACK_ROW_LENGTH if it is greater than zero, the width argument to the pixel routine otherwise), and a is the value of GL_UNPACK_ALIGNMENT. If a<s, then it is as if a=s. In the case of 1-bit values, the location of the next row is obtained by skipping i = 8 * a * ceiling(s*w / 8*a) bytes. The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue. GL_UNPACK_IMAGE_HEIGHT_EXT If greater than zero, GL_UNPACK_IMAGE_HEIGHT_EXT defines the number of rows in an image. If the first pixel of an image is placed at location p in memory, then the location of the first pixel of the next image is obtained by skipping j=ih elements, where i is the offset from the beginning of one row in an image to the beginning of the next row in the image (as described in the GL_UNPACK_ROW_LENGTH section) and h is the height of the image. h is equal the value specified with GL_PACK_IMAGE_HEIGHT_EXT if this value is greater than zero and is equal to the height argument to the pixel routine otherwise. If the routine has no height argument and the height was not specified with GL_PACK_IMAGE_HEIGHT_EXT (or was specified as zero), h is the height of the data to be downloaded. GL_UNPACK_IMAGE_DEPTH_SGIS If greater than zero, GL_UNPACK_IMAGE_DEPTH_SGIS defines the number of images in a volume. If the first pixel of a volume is placed at location p in memory, then the location of the first pixel of the next volume is obtained by skipping k=jd bytes, where j is the offset from the beginning of one image to the beginning of the next image (as described in the GL_UNPACK_IMAGE_HEIGHT_EXT section) and d is the depth of the image. d is equal to the value specified with GL_UNPACK_IMAGE_DEPTH_SGIS if this value is greater than zero and is equal to the depth argument to the pixel routine otherwise. If the routine has no depth argument and the depth was not specified with GL_PACK_IMAGE_DEPTH_SGIS (or was specified as zero), d is the depth of the data to be downloaded. GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS These values are provided mainly as a convenience to the programmer; except when 1-bit per pixel data is being specified, they provide no functionality that cannot be duplicated simply by incrementing the pointer p passed to the command which is reading pixel data from client memory. For multi-bit data types, setting GL_UNPACK_SKIP_PIXELS to l is equivalent to incrementing the pointer just once by sl bytes, where s is the number of bytes in each pixel (as described above in the GL_UNPACK_ROW_LENGTH section). Setting GL_UNPACK_SKIP_ROWS to m is equivalent to incrementing the pointer just once by im bytes, where i is the number of bytes per row, as computed above in the GL_UNPACK_ROW_LENGTH section. When 1-bit (GL_BITMAP) data is being read, setting GL_UNPACK_SKIP_PIXELS to l is equivalent to incrementing the pointer just once by floor(l/8) bytes. For each row of the image, the image data read will begin at bit l%8 of the byte, where 0 is the most significant bit. Other bits of the byte will be ignored. Note that the adjustment to the pointer takes place just once, before the start of the pixel transfer; specifying a value of one for GL_UNPACK_SKIP_ROWS does not cause every other row of the image to be skipped. GL_UNPACK_SKIP_IMAGES_EXT Setting GL_UNPACK_SKIP_IMAGES_EXT to n is equivalent to incrementing the pointer passed to the routine just once by jn bytes, where j is the number of bytes per image, as computed above in the GL_UNPACK_IMAGE_HEIGHT_EXT section. The offset specified by GL_UNPACK_SKIP_IMAGES_EXT is applied only to data of three or more dimensions. The offset is applied in addition to the offsets specified by GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS as described above. GL_UNPACK_SKIP_VOLUMES_SGIS Setting GL_UNPACK_SKIP_VOLUMES_SGIS to o is equivalent to incrementing the pointer passed just once by ko bytes, where k is the number of bytes per volume, as computed in the GL_UNPACK_IMAGE_DEPTH_SGIS section. The offset specified by GL_UNPACK_SKIP_VOLUMES_SGIS is applied only to data of four or more dimensions. The offset is applied in addition to the offsets specified by GL_UNPACK_SKIP_PIXELS, GL_UNPACK_SKIP_ROWS, and GL_UNPACK_SKIP_IMAGES_EXT as described above. GL_UNPACK_ALIGNMENT Specifies the alignment requirements for the start of each pixel row in memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes), 4 (word alignment), and 8 (rows start on double-word boundaries). The following table gives the type, initial value, and range of valid values for each of the storage parameters that can be set with glPixelStore. pname type initial value valid range _____________________________________________________________________ GL_PACK_SWAP_BYTES Boolean false true or false GL_PACK_LSB_FIRST Boolean false true or false GL_PACK_ROW_LENGTH integer 0 [0,oo) GL_PACK_SKIP_ROWS integer 0 [0,oo) GL_PACK_SKIP_PIXELS integer 0 [0,oo) GL_PACK_ALIGNMENT integer 4 1, 2, 4, or 8 GL_PACK_IMAGE_HEIGHT_EXT integer 0 [0,oo) GL_PACK_IMAGE_DEPTH_SGIS integer 0 [0,oo) GL_PACK_SKIP_IMAGES_EXT integer 0 [0,oo) GL_PACK_SKIP_VOLUMES_SGIS integer 0 [0,oo) _____________________________________________________________________ GL_UNPACK_SWAP_BYTES Boolean false true or false GL_UNPACK_LSB_FIRST Boolean false true or false GL_UNPACK_ROW_LENGTH integer 0 [0,oo) GL_UNPACK_SKIP_ROWS integer 0 [0,oo) GL_UNPACK_SKIP_PIXELS integer 0 [0,oo) GL_UNPACK_ALIGNMENT integer 4 1, 2, 4, or 8 GL_UNPACK_IMAGE_HEIGHT_EXT integer 0 [0,oo) GL_UNPACK_IMAGE_DEPTH_SGIS integer 0 [0,oo) GL_UNPACK_SKIP_IMAGES_EXT integer 0 [0,oo) GL_UNPACK_SKIP_VOLUMES_SGIS integer 0 [0,oo) glPixelStoref can be used to set any pixel store parameter. If the parameter type is Boolean, then if param is 0.0, the parameter is false; otherwise it is set to true. If pname is a integer type parameter, param is rounded to the nearest integer. Likewise, glPixelStorei can also be used to set any of the pixel store parameters. Boolean parameters are set to false if param is 0 and true otherwise. NOTES The pixel storage modes in effect when commands which read pixel data from client memory (glDrawPixels, glTexImage1D etc) are placed in a display list control the interpretation of memory data. The pixel storage modes in effect when a display list is executed are not significant. ERRORS GL_INVALID_ENUM is generated if pname is not an accepted value. GL_INVALID_VALUE is generated if a negative row length, pixel skip, row skip, image height, image skip, image depth, or volume skip value is specified, or if alignment is specified as other than 1, 2, 4, or 8. GL_INVALID_OPERATION is generated if glPixelStore is executed between the execution of glBegin and the corresponding execution of glEnd. ASSOCIATED GETS glGet with argument GL_PACK_SWAP_BYTES glGet with argument GL_PACK_LSB_FIRST glGet with argument GL_PACK_ROW_LENGTH glGet with argument GL_PACK_SKIP_ROWS glGet with argument GL_PACK_SKIP_PIXELS glGet with argument GL_PACK_ALIGNMENT glGet with argument GL_PACK_IMAGE_HEIGHT_EXT glGet with argument GL_PACK_IMAGE_DEPTH_SGIS glGet with argument GL_PACK_SKIP_IMAGES_EXT glGet with argument GL_PACK_SKIP_VOLUMES_SGIS glGet with argument GL_UNPACK_SWAP_BYTES glGet with argument GL_UNPACK_LSB_FIRST glGet with argument GL_UNPACK_ROW_LENGTH glGet with argument GL_UNPACK_SKIP_ROWS glGet with argument GL_UNPACK_SKIP_PIXELS glGet with argument GL_UNPACK_ALIGNMENT glGet with argument GL_UNPACK_IMAGE_HEIGHT_EXT glGet with argument GL_UNPACK_IMAGE_DEPTH_SGIS glGet with argument GL_UNPACK_SKIP_IMAGES_EXT glGet with argument GL_UNPACK_SKIP_VOLUMES_SGIS SEE ALSO glBitmap, glColorTableSGI, glConvolutionFilter1DEXT, glConvolutionFilter2DEXT, glDrawPixels, glPixelMap, glPixelTransfer, glPixelZoom, glPolygonStipple, glReadPixels, glSeparableFilter2DEXT, glTexImage1D, glTexImage2D, glTexImage3DEXT, glTexImage4DSGIS, glTexSubImage1DEXT, glTexSubImage2DEXT, glTexSubImage3DEXT, glTexSubImage4DSGIS