glCopyTexImage1D function

Article
12/11/2020

The glCopyTexImage1D function copies pixels from the framebuffer into a one-dimensional texture image.

Syntax

void WINAPI glCopyTexImage1D(
   GLenum  target,
   GLint   level,
   GLenum  internalFormat,
   GLint   x,
   GLint   y,
   GLsizei width,
   GLint   border
);

Parameters

target

The target for which the image data will be changed. Must have the value GL_TEXTURE_1D.

level

The level-of-detail number. Level 0 is the base image. Level n is the nth mipmap reduction image.

internalFormat

The internal format and resolution of the texture data. This parameter must be one of the following symbolic values.

Constant	R Bits	G Bits	B Bits	A Bits	L Bits	I Bits
GL_ALPHA
GL_ALPHA4				4
GL_ALPHA8				8
GL_ALPHA12				12
GL_ALPHA16				16
GL_LUMINANCE
GL_LUMINANCE4					4
GL_LUMINANCE8					8
GL_LUMINANCE12					12
GL_LUMINANCE16					16
GL_LUMINANCE_ALPHA
GL_LUMINANCE4_ALPHA4				4	4
GL_LUMINANCE6_ALPHA2				2	6
GL_LUMINANCE8_ALPHA8				8	8
GL_LUMINANCE12_ALPHA4				4	12
GL_LUMINANCE12_ALPHA12				12	12
GL_LUMINANCE16_ALPHA16				16	16
GL_INTENSITY
GL_INTENSITY4						4
GL_INTENSITY8						8
GL_INTENSITY12						12
GL_INTENSITY16						16
GL_RGB
GL_R3_G3_B2	3	3	2
GL_RGB4	4	4	4
GL_RGB5	5	5	5
GL_RGB8	8	8	8
GL_RGB10	10	10	10
GL_RGB12	12	12	12
GL_RGB16	16	16	16
GL_RGBA
GL_RGBA2	2	2	2	2
GL_RGBA4	4	4	4	4
GL_RGB5_A1	5	5	5	1
GL_RGBA8	8	8	8	8
GL_RGB10_A2	10	10	10	2
GL_RGBA12	12	12	12	12
GL_RGBA16	16	16	16	16

x

The window x-plane coordinate of the lower-left corner of the row of pixels to be copied.

y

The window y-plane coordinate of the lower-left corner of the row of pixels to be copied.

width

The width of the texture image. Must be zero or 2n + 2(border) for some integer n. The height of the texture image is 1.

border

The width of the border. Must be either zero or 1.

Return value

This function does not return a value.

Error codes

The following error codes can be retrieved by the glGetError function.

Name	Meaning
GL_INVALID_ENUM	target was not an accepted value.
GL_INVALID_VALUE	level was less than zero or greater than log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE	border was not zero or 1.
GL_INVALID_VALUE	width was less than zero, greater than 2 + GL_MAX_TEXTURE_SIZE, or width cannot be represented as 2n +(border) for some integer n.
GL_INVALID_OPERATION	The function was called between a call to glBegin and the corresponding call to glEnd.

Remarks

The glCopyTexImage1D function defines a one-dimensional texture image using pixels from the current framebuffer, rather than from main memory as is the case for glTexImage1D.

Using the mipmap level specified with level, texture arrays are defined as a pixel row aligned with the lower-left corner of the window at the coordinates specified by x and y, with a length equal to width + 2 * border. The internal format of the texture array is specified with the internalFormat parameter.

The glCopyTexImage1D function processes the pixels in a row in the same way as glCopyPixels, except that before the final conversion of the pixels, all pixel component values are clamped to the range [0,1] and converted to the texture's internal format for storage in the texture array. Pixel ordering is determined with lower x coordinates corresponding to lower texture coordinates. If any of the pixels within a specified row of the current framebuffer are outside the window associated with the current rendering context, then their values are undefined.

You cannot include calls to glCopyTexImage1D in display lists.

Note

The glCopyTexImage1D function is only available in OpenGL version 1.1 or later.

Texturing has no effect in color-index mode. The glPixelStore and glPixelTransfer functions affect texture images in exactly the way they affect glDrawPixels.

The following function retrieves information related to glCopyTexImage1D:

glIsEnabled with argument GL_TEXTURE_1D

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Header	Gl.h
Library	Opengl32.lib
DLL	Opengl32.dll