一、Creating an OpenGL context（创建一个OpenGL环境）

This section describes how to configure an OpenGL context. For most applications the information described here is far too low-level to be of any concern, however more advanced applications can take advantage of the complete control pyglet provides.

本节描述如何配置一个OpenGL上下文。对于大多数应用程序这里描述的信息太低级的任何问题,但是更高级的应用程序可以利用pyglet提供完整的控制。

Displays, screens, configs and contexts（显示器,屏幕,配置和上下文）

image.png

Flow of construction, from the singleton Platform to a newly created Window with its Context.

独立平台的建设,一个新创建的窗口,其上下文。

Contexts and configs（环境和配置）

When you draw on a window in pyglet, you are drawing to an OpenGL context. Every window has its own context, which is created when the window is created. You can access the window’s context via its context attribute.

当你在pyglet画在一个窗口时,你画一个OpenGL上下文。每个窗口都有自己的背景,这是创建窗口时创建的。你可以通过它访问窗口的背景context属性。

The context is created from an OpenGL configuration (or “config”), which describes various properties of the context such as what color format to use, how many buffers are available, and so on. You can access the config that was used to create a context via the context’s config attribute.

上下文创建从一个OpenGL配置(或“config”),用于描述上下文的各种属性,如格式使用什么颜色,多少缓冲区,等等。您可以访问配置用于创建一个上下文通过上下文的“config”属性。

For example, here we create a window using the default config and examine some of its properties:

例如,在这里我们使用默认的配置创建一个窗口并检查它的一些属性:

>>> import pyglet
>>> window = pyglet.window.Window()
>>> context = window.context
>>> config = context.config
>>> config.double_buffer
c_int(1)
>>> config.stereo
c_int(0)
>>> config.sample_buffers
c_int(0)

Note that the values of the config’s attributes are all ctypes instances. This is because the config was not specified by pyglet. Rather, it has been selected by pyglet from a list of configs supported by the system. You can make no guarantee that a given config is valid on a system unless it was provided to you by the system.

注意,配置的属性的值都是ctypes实例。这是因为配置被pyglet未指定。相反,它被pyglet选择从列表中支持的配置系统。你可以不能保证给定系统上配置是有效的,除非它是提供给您的系统。

pyglet simplifies the process of selecting one of the system’s configs by allowing you to create a “template” config which specifies only the values you are interested in. See Simple context configuration for details.

pyglet简化的过程中选择一个系统的配置,允许你创建一个“ template”配置指定只有您感兴趣的值。有关详细信息,请参阅Simple context configuration。

Displays（显示）

The system may actually support several different sets of configs, depending on which display device is being used. For example, a computer with two video cards may not support the same configs on each card. Another example is using X11 remotely: the display device will support different configurations than the local driver. Even a single video card on the local computer may support different configs for two monitors plugged in.

系统可以支持几个不同的配置,这取决于显示设备。例如,一台电脑和两个显卡可能不支持同样的配置在每个卡。另一个例子是使用远程X11:显示设备将支持不同的配置比当地司机。甚至一个单一的视频卡在本地计算机可能支持不同配置两个显示器插入。

In pyglet, a Display is a collection of “screens” attached to a single display device. On Linux, the display device corresponds to the X11 display being used. On Windows and Mac OS X, there is only one display (as these operating systems present multiple video cards as a single virtual device).

pyglet,显示是“屏幕”的集合在一个显示设备。在Linux上,显示设备对应于X11显示使用。在Windows和Mac OS X上,只有一个显示(因为这些操作系统存在多个视频卡作为一个单独的虚拟设备)。

There is a singleton class Platform which provides access to the display(s); this represents the computer on which your application is running. It is usually sufficient to use the default display:

有一个单例类平台提供访问显示(Platform);这是您的应用程序的计算机正在运行。它通常是足以使用默认的显示:

>>> platform = pyglet.window.get_platform()
>>> display = platform.get_default_display()

On X11, you can specify the display string to use, for example to use a remotely connected display. The display string is in the same format as used by the DISPLAY environment variable:

在X11,您可以指定要使用的显示字符串,例如使用远程连接显示。在相同的格式显示字符串使用的显示环境变量:

>>> display = platform.get_display('remote:1.0')

You use the same string to specify a separate X11 screen [1]:

你使用相同的字符串来指定一个单独的X11屏幕[1]:

>>> display = platform.get_display(':0.1')

Screens（屏幕）

Once you have obtained a display, you can enumerate the screens that are connected. A screen is the physical display medium connected to the display device; for example a computer monitor, TV or projector. Most computers will have a single screen, however dual-head workstations and laptops connected to a projector are common cases where more than one screen will be present.

一旦你得到一个显示器,你可以列举连接的屏幕。屏幕是物理显示介质连接到显示装置;例如,电脑显示器、电视或者投影仪。大多数计算机将有一个屏幕,然而双头工作站和笔记本电脑连接投影仪是常见的超过一个屏幕将会出现的情况。

In the following example the screens of a dual-head workstation are listed:

在接下来的例子中列出一个双头的工作站的屏幕:

>>> for screen in display.get_screens():
...     print(screen)
...
XlibScreen(screen=0, x=1280, y=0, width=1280, height=1024, xinerama=1)
XlibScreen(screen=0, x=0, y=0, width=1280, height=1024, xinerama=1)

Because this workstation is running Linux, the returned screens are XlibScreen, a subclass of Screen. The screen and xinerama attributes are specific to Linux, but the x, y, width and height attributes are present on all screens, and describe the screen’s geometry, as shown below.

因为这个工作站运行Linux, XlibScreen返回的屏幕,屏幕上的一个子类。屏幕和xinerama属性是特定于Linux,但x, y,宽度和高度属性出现在所有屏幕上,并描述屏幕上的几何图形,如下所示。

image.png

Example arrangement of screens and their reported geometry. Note that the primary display (marked “1”) is positioned on the right, according to this particular user’s preference.

例子安排报告的屏幕和他们的几何学。注意,主显示(标记为“1”)是定位在右边,根据这一特定用户的偏好。

There is always a “default” screen, which is the first screen returned by get_screens(). Depending on the operating system, the default screen is usually the one that contains the taskbar (on Windows) or menu bar (on OS X). You can access this screen directly using get_default_screen().

总有一个“默认”屏幕,这是第一个屏幕返回get_screens ()。根据操作系统默认的屏幕通常是一个包含任务栏(在Windows上)或菜单栏(在OS X)。您可以访问此屏幕直接使用get_default_screen ()。

<colgroup><col class="label"><col></colgroup>
| [1] | Assuming Xinerama is not being used to combine the screens. If Xinerama is enabled, use screen 0 in the display string, and select a screen in the same manner as for Windows and Mac OS X. |

假设Xinerama不是被用来结合屏幕。如果启用了Xinerama,使用屏幕0显示字符串,并选择屏幕上以同样的方式为Windows和Mac OS X。

作者Mac电脑以上测试结果：

image.png

OpenGL configuration options（OpenGL的配置选项）

When configuring or selecting a Config, you do so based on the properties of that config. pyglet supports a fixed subset of the options provided by AGL, GLX, WGL and their extensions. In particular, these constraints are placed on all OpenGL configs:

当配置或选择一个配置,你这么做基于属性的配置。pyglet支持固定提供的选项的子集,AGL GLX, WGL及其扩展。特别是,这些限制都放在OpenGL配置:

• Buffers are always component (RGB or RGBA) color, never palette indexed.

缓冲区总是组件(RGB或RGBA)颜色,从不调色板索引。

• The “level” of a buffer is always 0 (this parameter is largely unsupported by modern OpenGL drivers anyway).

“level”一个缓冲区总是0(该参数在很大程度上是不受支持的现代OpenGL驱动)。

• There is no way to set the transparent color of a buffer (again, this GLX-specific option is not well supported).

没有办法设置缓冲区的透明色(这GLX-specific选项不支持)。

• There is no support for pbuffers (equivalent functionality can be achieved much more simply and efficiently using framebuffer objects).

不支持pbuffers(等效功能可以实现更加简单和高效使用framebuffer对象)。

The visible portion of the buffer, sometimes called the color buffer, is configured with the following attributes:

缓冲区的可见部分,有时被称为颜色缓冲区,配置了以下属性:

• buffer_size

Number of bits per sample. Common values are 24 and 32, which each dedicate 8 bits per color component. A buffer size of 16 is also possible, which usually corresponds to 5, 6, and 5 bits of red, green and blue, respectively.

每个抽样的比特数。共同的价值观是24到32,每个用8位/颜色组件。缓冲区大小为16也是可能的,通常对应于5、6和5位的红色,绿色和蓝色。

Usually there is no need to set this property, as the device driver will select a buffer size compatible with the current display mode by default.

通常没有必要设置这个属性,为设备驱动程序将选择一个缓冲区大小兼容当前默认显示模式。

• red_size, blue_size, green_size, alpha_size

These each give the number of bits dedicated to their respective color component. You should avoid setting any of the red, green or blue sizes, as these are determined by the driver based on the buffer_size property.

这些都给各自专用的比特数颜色组件。你应该避免设置任何红色,绿色或蓝色大小,因为这些是由司机根据buffer_size属性。

If you require an alpha channel in your color buffer (for example, if you are compositing in multiple passes) you should specify alpha_size=8 to ensure that this channel is created.

如果你需要一个alpha通道颜色缓冲区(例如,如果你在多个通行证)合成应该指定alpha_size = 8,确保创建这个通道。

• sample_buffers and samples

Configures the buffer for multisampling, in which more than one color sample is used to determine the color of each pixel, leading to a higher quality, antialiased image.

配置的缓冲multisampling,不止一个颜色样品用于确定每个像素的颜色,导致更高的质量,平滑的图像。

Enable multisampling by setting sample_buffers=1, then give the number of samples per pixel to use in samples. For example, samples=2 is the fastest, lowest-quality multisample configuration. A higher-quality buffer (with a compromise in performance) is possible with samples=4.

使multisampling通过设置sample_buffers = 1,然后给每个像素的样本数量在样品中使用。例如,= 2是最快的样品,质量最差multisample配置。高质量的缓冲性能(妥协)是可能的样品= 4。

Not all video hardware supports multisampling; you may need to make this a user-selectable option, or be prepared to automatically downgrade the configuration if the requested one is not available.

并不是所有的视频硬件支持multisampling;你可能都需要让这个可选的选项,或者准备自动降级配置如果要求一个不可用。

• stereo

Creates separate left and right buffers, for use with stereo hardware. Only specialised video hardware such as stereoscopic glasses will support this option. When used, you will need to manually render to each buffer, for example using glDrawBuffers.

创建单独的左和右的缓冲区,用于立体声硬件。只有专业的视频硬件如立体眼镜会支持这个选项。使用时,您将需要手动渲染每个缓冲区,例如使用glDrawBuffers。

• double_buffer

Create separate front and back buffers. Without double-buffering, drawing commands are immediately visible on the screen, and the user will notice a visible flicker as the image is redrawn in front of them.

创建单独的前后缓冲。没有双缓冲,在屏幕上绘图命令立即可见,用户会注意到一个明显的闪烁图像重绘在他们面前。

It is recommended to set double_buffer=True, which creates a separate hidden buffer to which drawing is performed. When the Window.flip is called, the buffers are swapped, making the new drawing visible virtually instantaneously.

建议设置double_buffer = True,创建一个单独的图纸执行隐藏缓冲。当窗口。翻转,交换缓冲区,使新的图可见几乎瞬间。

In addition to the color buffer, several other buffers can optionally be created based on the values of these properties:

除了颜色缓冲区,其他几个缓冲区可以创建基于这些属性的值:

• depth_size

A depth buffer is usually required for 3D rendering. The typical depth size is 24 bits. Specify 0 if you do not require a depth buffer.

深度缓冲通常需要3 d渲染。典型的深度尺寸是24位。指定0如果你不需要深度缓冲。

• stencil_size

The stencil buffer is required for masking the other buffers and implementing certain volumetric shadowing algorithms. The typical stencil size is 8 bits; or specify 0 if you do not require it.

模板缓存需要屏蔽其他缓冲区和实现特定体积阴影算法。典型的模板大小是8位;如果你不需要它或者指定0。

• accum_red_size, accum_blue_size, accum_green_size, accum_alpha_size

The accumulation buffer can be used for simple antialiasing, depth-of-field, motion blur and other compositing operations. Its use nowadays is being superceded by the use of floating-point textures, however it is still a practical solution for implementing these effects on older hardware.

累积缓冲区可以用于简单的反锯齿,景深效果,运动模糊和其他合成操作。使用它现在被使用浮点纹理,但是这仍然是一个实用的解决方案实现这些效果在旧的硬件。

If you require an accumulation buffer, specify 8 for each of these attributes (the alpha component is optional, of course).

如果你需要一个累积缓冲区,为每个这些属性指定8(α组件是可选的,当然)。

• aux_buffers

Each auxilliary buffer is configured the same as the colour buffer. Up to four auxilliary buffers can typically be created. Specify 0 if you do not require any auxilliary buffers.

每个辅助缓冲区配置一样的颜色缓冲区。4辅助缓冲区通常可以创建。指定0,如果你不需要任何辅助缓冲区。

Like the accumulation buffer, auxilliary buffers are used less often nowadays as more efficient techniques such as render-to-texture are available. They are almost universally available on older hardware, though, where the newer techniques are not possible.

像累积缓冲区,辅助缓冲区使用少如今更为高效的技术如纹理渲染是可用的。他们几乎普遍可用在旧硬件,虽然,更新的技术是不可能的。

If you wish to work with OpenGL directly, you can request a higher level context. This is required if you wish to work with the modern OpenGL programmable pipeline. Please note, however, that pyglet currently uses legacy OpenGL functionality for many of it’s internal modules (such as the text, graphics, and sprite modules). Requesting a higher version context will currently prevent usage of these modules.

如果你想直接使用OpenGL,您可以请求一个更高的水平。这是必需的,如果你想工作与现代OpenGL可编程管线。然而,请注意,pyglet目前使用遗留OpenGL许多它的内部功能模块(如文本、图形和雪碧模块)。要求更高的版本目前环境将防止这些模块的使用。

• major_version

This will be either 3 or 4, for an OpenGL 3.x or 4.x context.

这将是3或4,OpenGL 3。x或4。x上下文。

• minor_version

The requested minor version of the context. In some cases, the OpenGL driver may return a higher version than requested.

请求的上下文的小版本。在某些情况下,OpenGL驱动可能返回一个版本高于要求。

• forward_compatible

Setting this to True will ask the driver to exclude legacy OpenGL features from the context. Khronos does not recommend this option.

设置为True会问司机排除遗留OpenGL特性从上下文。Khronos不建议此选项。

Note To request a higher higher version OpenGL context on Mac OSX, it is necessary to disable the pyglet shadow context. To do this, set the pyglet option pyglet.options['shadow_window'] to False before creating a Window.

注意请求更高更高版本Mac OSX上OpenGL上下文,需要禁用pyglet影子上下文。为此,设置pyglet pyglet选项。选项(“shadow_window”)设置为假之后创建一个窗口。

The default configuration（缺省配置）

If you create a Window without specifying the context or config, pyglet will use a template config with the following properties:

如果您创建一个窗口没有指定上下文或配置,pyglet将使用一个模板配置具有以下属性:

image.png

Simple context configuration（简单context配置）

A context can only be created from a config that was provided by the system. Enumerating and comparing the attributes of all the possible configs is a complicated process, so pyglet provides a simpler interface based on “template” configs.

只可以创建一个上下文提供的配置系统。列举和比较所有可能的属性配置是一个复杂的过程,所以pyglet基于“模板”提供了一个简单的接口配置。

To get the config with the attributes you need, construct a Config and set only the attributes you are interested in. You can then supply this config to the Window constructor to create the context.

得到你需要的配置属性,构建一套配置,只有你感兴趣的属性。然后你可以供应这个配置窗口构造函数创建上下文。

For example, to create a window with an alpha channel:

例如,要创建一个窗口,一个alpha通道:

config = pyglet.gl.Config(alpha_size=8)
window = pyglet.window.Window(config=config)

It is sometimes necessary to create the context yourself, rather than letting the Window constructor do this for you. In this case use get_best_config() to obtain a “complete” config, which you can then use to create the context:

有时需要自己创建上下文,而不是让窗口构造函数为你这样做。在这种情况下使用get_best_config()获得“ complete”配置,您可以使用它来创建上下文:

重要示例：

platform = pyglet.window.get_platform()
display = platform.get_default_display()
screen = display.get_default_screen()

template = pyglet.gl.Config(alpha_size=8)
config = screen.get_best_config(template)
context = config.create_context(None)
window = pyglet.window.Window(context=context)

Note that you cannot create a context directly from a template (any Config you constructed yourself). The Window constructor performs a similar process to the above to create the context if a template config is given.

注意,不能直接从一个模板创建一个上下文(任何配置构造你自己)。上面的窗口构造函数执行类似的过程来创建上下文,如果模板配置。

Not all configs will be possible on all machines. The call to get_best_config() will raise NoSuchConfigException if the hardware does not support the requested attributes. It will never return a config that does not meet or exceed the attributes you specify in the template.

并不是所有的配置将在所有可能的机器。到get_best_config()的调用将提高NoSuchConfigException如果硬件不支持请求的属性。它永远不会返回一个配置,不符合或超过您所指定的属性模板中。

You can use this to support newer hardware features where available, but also accept a lesser config if necessary. For example, the following code creates a window with multisampling if possible, otherwise leaves multisampling off:

您可以使用它来支持新硬件功能可用,而且在必要时接受较小的配置。例如,下面的代码创建一个窗口与multisampling如果可能,否则叶子multisampling:

重要示例

template = gl.Config(sample_buffers=1, samples=4)
try:
    config = screen.get_best_config(template)
except pyglet.window.NoSuchConfigException:
    template = gl.Config()
    config = screen.get_best_config(template)
window = pyglet.window.Window(config=config)

Selecting the best configuration(选择最佳的配置)

Allowing pyglet to select the best configuration based on a template is sufficient for most applications, however some complex programs may want to specify their own algorithm for selecting a set of OpenGL attributes.

允许pyglet选择最好的基于模板的配置足够的对于大多数应用程序,然而一些复杂的程序可能希望指定自己的算法选择一组OpenGL属性。

You can enumerate a screen’s configs using the get_matching_configs() method. You must supply a template as a minimum specification, but you can supply an “empty” template (one with no attributes set) to get a list of all configurations supported by the screen.

你可以列举一个屏幕的配置使用get_matching_configs()方法。您必须提供一个模板作为一个最低规格,但是你可以提供一个“空”的模板(一个没有属性集)来获得所有配置的列表支持的屏幕。

In the following example, all configurations with either an auxilliary buffer or an accumulation buffer are printed:

在以下示例中,所有配置与一个辅助缓冲区或积累缓冲印刷:

platform = pyglet.window.get_platform()
display = platform.get_default_display()
screen = display.get_default_screen()

for config in screen.get_matching_configs(gl.Config()):
    if config.aux_buffers or config.accum_red_size:
        print config

As well as supporting more complex configuration selection algorithms, enumeration allows you to efficiently find the maximum value of an attribute (for example, the maximum samples per pixel), or present a list of possible configurations to the user.

以及支持更复杂的配置选择算法,枚举可以有效地找到一个属性的最大值(例如,每个像素的最大样本),或现在可能的配置列表给用户。

Sharing objects between contexts(上下文之间共享对象)

Every window in pyglet has its own OpenGL context. Each context has its own OpenGL state, including the matrix stacks and current flags. However, contexts can optionally share their objects with one or more other contexts. Shareable objects include:

每一个窗口pyglet有自己的OpenGL上下文。每个环境都有自己的OpenGL状态,包括矩阵栈和当前的旗帜。然而,上下文可以分享他们的对象与一个或多个其他上下文。可共享的对象包括:

• Textures纹理

• Display lists显示列表

• Shader programs着色器程序

• Vertex and pixel buffer objects顶点和像素缓冲区对象

• Framebuffer objects (Framebuffer对象)

There are two reasons for sharing objects. The first is to allow objects to be stored on the video card only once, even if used by more than one window. For example, you could have one window showing the actual game, with other “debug” windows showing the various objects as they are manipulated. Or, a set of widget textures required for a GUI could be shared between all the windows in an application.

为共享对象有两个原因。第一个是允许对象存储在显卡上只有一次,即使使用多个窗口。例如,您可以有一个窗口显示实际的游戏,与其他“调试”窗口显示的各种对象操纵。或者一组部件材质需要GUI可以在应用程序之间共享所有的窗户。

The second reason is to avoid having to recreate the objects when a context needs to be recreated. For example, if the user wishes to turn on multisampling, it is necessary to recreate the context. Rather than destroy the old one and lose all the objects already created, you can

第二个原因是为了避免创建对象时需要重新创建一个上下文。例如,如果用户希望打开multisampling,有必要重新创建上下文。而不是摧毁旧的和失去的所有对象已经创建,你可以

1、Create the new context, sharing object space with the old context, then

创建新的背景下,与旧的分享对象空间上下文,然后

2、Destroy the old context. The new context retains all the old objects.

摧毁旧的上下文。新的上下文保留旧的对象。

pyglet defines an ObjectSpace: a representation of a collection of objects used by one or more contexts. Each context has a single object space, accessible via its object_space attribute.

pyglet定义了一个ObjectSpace:一个对象集合的表示由一个或多个上下文使用。每个上下文都有一个单独的对象空间,可以通过其object_space属性。

By default, all contexts share the same object space as long as at least one context using it is “alive”. If all the contexts sharing an object space are lost or destroyed, the object space will be destroyed also. This is why it is necessary to follow the steps outlined above for retaining objects when a context is recreated.

默认情况下,所有上下文共享相同的对象空间只要至少一个上下文中使用它是“活着”。如果所有的上下文共享对象空间丢失或被破坏,对象空间也将被摧毁。这就是为什么有必要按照上述步骤保留上下文时重新创建对象。

pyglet creates a hidden “shadow” context as soon as pyglet.gl is imported. By default, all windows will share object space with this shadow context, so the above steps are generally not needed. The shadow context also allows objects such as textures to be loaded before a window is created (see shadow_window in pyglet.options for further details).

pyglet创建一个隐藏的“影子”一旦pyglet上下文。gl是进口的。默认情况下,所有windows将与这个影子分享对象空间上下文,因此上述步骤一般都不需要。影子上下文还允许对象(如纹理加载之前创建一个窗口(见shadow_window pyglet。选择更多细节)。

When you create a Context, you tell pyglet which other context it will obtain an object space from. By default (when using theWindow constructor to create the context) the most recently created context will be used. You can specify another context, or specify no context (to create a new object space) in the Context constructor.

当您创建一个上下文,你告诉pyglet其他上下文,它将获得一个对象空间。(当使用窗口默认构造函数来创建上下文)最近将使用创建上下文。您可以指定另一个上下文,或指定任何上下文(创建一个新的对象空间)中构造函数。

It can be useful to keep track of which object space an object was created in. For example, when you load a font, pyglet caches the textures used and reuses them; but only if the font is being loaded on the same object space. The easiest way to do this is to set your own attributes on the ObjectSpace object.

它可能是有用的跟踪对象空间创建一个对象。例如,当您加载一个字体,pyglet缓存使用的纹理和重用;但前提是字体被加载到同一个对象空间。最简单的方法就是设定你自己的ObjectSpace对象上的属性。

In the following example, an attribute is set on the object space indicating that game objects have been loaded. This way, if the context is recreated, you can check for this attribute to determine if you need to load them again:

在接下来的例子中,一个属性被设置在对象空间表明游戏对象加载。这样,如果重新创建上下文,您可以检查这个属性来决定是否需要加载一遍:

context = pyglet.gl.get_current_context()
object_space = context.object_space
object_space.my_game_objects_loaded = True

Avoid using attribute names on ObjectSpace that begin with "pyglet", as they may conflict with an internal module.

避免使用属性名称的ObjectSpace开始“pyglet”,因为它们可能与内部模块之间的冲突。

二、The OpenGL interface（OpenGL接口）

pyglet provides an interface to OpenGL and GLU. The interface is used by all of pyglet’s higher-level API’s, so that all rendering is done efficiently by the graphics card, rather than the operating system. You can access this interface directly; using it is much like using OpenGL from C.

OpenGL和GLU pyglet提供了一个接口。所使用的接口是pyglet所有的高级API,以便所有渲染完成有效的图形卡,而不是操作系统。你可以直接访问该接口;使用它就像使用OpenGL从C。

The interface is a “thin-wrapper” around libGL.so on Linux, opengl32.dll on Windows and OpenGL.framework on OS X. The pyglet maintainers regenerate the interface from the latest specifications, so it is always up-to-date with the latest version and almost all extensions.

libGL周围的接口是一个“瘦包装器”。在Linux上,opengl32。dll在OS x Windows和OpenGL.framework pyglet维护者再生最新的接口规范,所以它总是最新的版本和几乎所有的扩展。

The interface is provided by the pyglet.gl package. To use it you will need a good knowledge of OpenGL, C and ctypes. You may prefer to use OpenGL without using ctypes, in which case you should investigate PyOpenGL. PyOpenGL provides similar functionality with a more “Pythonic” interface, and will work with pyglet without any modification.

由pyglet提供的接口。gl包。使用OpenGL的你需要一个好的知识,C和ctypes。你可能更愿意使用OpenGL不用ctypes,在这种情况下你应该调查PyOpenGL。PyOpenGL为类似的功能提供了一个更“Pythonic”界面,并将与pyglet没有任何修改。

Using OpenGL（使用OpenGL）

Documentation of OpenGL and GLU are provided at the OpenGL website and (more comprehensively) in the OpenGL Programming SDK.

文档提供了OpenGL和GLU的OpenGL网站和OpenGL编程SDK(更全面)。

Importing the package gives access to OpenGL, GLU, and all OpenGL registered extensions. This is sufficient for all but the most advanced uses of OpenGL:

导入包给了OpenGL, GLU, OpenGL注册扩展。这是足够的对于所有但OpenGL的最先进的用途:

from pyglet.gl import *

All function names and constants are identical to the C counterparts. For example, the following program draws a triangle on the screen:

所有函数名和常数C同行完全相同。例如,以下程序在屏幕上画了一个三角形:

from pyglet.gl import *

# Direct OpenGL commands to this window.
window = pyglet.window.Window()

@window.event
def on_draw():
    glClear(GL_COLOR_BUFFER_BIT)
    glLoadIdentity()
    glBegin(GL_TRIANGLES)
    glVertex2f(0, 0)
    glVertex2f(window.width, 0)
    glVertex2f(window.width, window.height)
    glEnd()

pyglet.app.run()

作者亲测，效果图如下：

image.png

Some OpenGL functions require an array of data. These arrays must be constructed as ctypes arrays of the correct type. The following example draw the same triangle as above, but uses a vertex array instead of the immediate-mode functions. Note the construction of the vertex array using a one-dimensional ctypes array of GLfloat:

一些OpenGL函数需要一个数组的数据。这些数组必须构造成ctypes正确类型的数组。下面的例子画上面的三角形一样,但使用顶点数组而不是立即寻址模式的功能。注意建设的顶点数组使用一维数组ctypes是GLfloat:

from pyglet.gl import *

window = pyglet.window.Window()

vertices = [0, 0,
            window.width, 0,
            window.width, window.height]
vertices_gl_array = (GLfloat * len(vertices))(*vertices)

glEnableClientState(GL_VERTEX_ARRAY)
glVertexPointer(2, GL_FLOAT, 0, vertices_gl_array)

@window.event
def on_draw():
    glClear(GL_COLOR_BUFFER_BIT)
    glLoadIdentity()
    glDrawArrays(GL_TRIANGLES, 0, len(vertices) // 2)

pyglet.app.run()

Similar array constructions can be used to create data for vertex buffer objects, texture data, polygon stipple data and the map functions.

类似数组结构顶点缓冲区可用于创建数据对象,纹理数据,多边形点画数据和地图功能。

Resizing the window（改变窗口大小）

pyglet sets up the viewport and an orthographic projection on each window automatically. It does this in a default on_resize()handler defined on Window:

pyglet设置窗口,每个窗口自动正射投影。它在默认on_resize()处理程序定义在窗口:

@window.event
def on_resize(width, height):
    glViewport(0, 0, width, height)
    glMatrixMode(gl.GL_PROJECTION)
    glLoadIdentity()
    glOrtho(0, width, 0, height, -1, 1)
    glMatrixMode(gl.GL_MODELVIEW)

If you need to define your own projection (for example, to use a 3-dimensional perspective projection), you should override this event with your own; for example:

如果你需要定义自己的投影(例如,使用三维透视投影),你应该覆盖这个与自己的事件;例如:

@window.event
def on_resize(width, height):
    glViewport(0, 0, width, height)
    glMatrixMode(GL_PROJECTION)
    glLoadIdentity()
    gluPerspective(65, width / float(height), .1, 1000)
    glMatrixMode(GL_MODELVIEW)
    return pyglet.event.EVENT_HANDLED

Note that the on_resize() handler is called for a window the first time it is displayed, as well as any time it is later resized.

注意on_resize()处理程序是第一次呼吁一个窗口显示,以及以后任何时间调整。

Error checking（错误检查）

By default, pyglet calls glGetError after every GL function call (except where such a check would be invalid). If an error is reported, pyglet raises GLException with the result of gluErrorString as the message.

默认情况下,pyglet调用glGetError每次GL函数调用(除非这种支票是无效的)。如果一个错误报告,pyglet提出GLException gluErrorString作为消息的结果。

This is very handy during development, as it catches common coding errors early on. However, it has a significant impact on performance, and is disabled when python is run with the -O option.

在开发过程中这是非常方便的,因为它捕获在早期常见的编码错误。然而,对性能有重大的影响,当python运行时使用- o选项禁用。

You can also disable this error check by setting the following option before importing pyglet.gl or pyglet.window:

你也可以禁用这个错误检查进口pyglet之前通过设置以下选项。gl或pyglet.window:

# Disable error checking for increased performance
pyglet.options['debug_gl'] = False

from pyglet.gl import *

Setting the option after importing pyglet.gl will have no effect. Once disabled, there is no error-checking overhead in each GL call.

进口pyglet后设置选项。gl将没有影响。一旦禁用,没有错误检查每个GL调用的开销。

Using extension functions（使用扩展函数）

Before using an extension function, you should check that the extension is implemented by the current driver. Typically this is done using glGetString(GL_EXTENSIONS), but pyglet has a convenience module, pyglet.gl.gl_info that does this for you:

使用一个扩展函数之前,你应该检查扩展由当前驱动程序实现。通常这样做是使用glGetString (GL_EXTENSIONS),但pyglet方便模块,pyglet.gl。gl_info做这个给你:

if pyglet.gl.gl_info.have_extension('GL_ARB_shadow'):
    # ... do shadow-related code.
else:
    # ... raise an exception, or use a fallback method

You can also easily check the version of OpenGL:

你也可以很容易地检查OpenGL的版本:

if pyglet.gl.gl_info.have_version(1,5):
    # We can assume all OpenGL 1.5 functions are implemented.

Remember to only call the gl_info functions after creating a window.

后记得只调用gl_info函数创建一个窗口。

There is a corresponding glu_info module for checking the version and extensions of GLU.

有一个相应的glu_info检查GLU的版本和扩展模块。

nVidia often release hardware with extensions before having them registered officially. When you import * from pyglet.gl you import only the registered extensions. You can import the latest nVidia extensions with:

nVidia经常释放硬件扩展之前让他们正式注册。当你从pyglet进口*。gl你只进口注册扩展。您可以导入最新的nVidia扩展:

from pyglet.gl.glext_nv import *

Using multiple windows（使用多个窗口）

pyglet allows you to create and display any number of windows simultaneously. Each will be created with its own OpenGL context, however all contexts will share the same texture objects, display lists, shader programs, and so on, by default [1]. Each context has its own state and framebuffers.

pyglet允许您创建并显示任意数量的同时窗户。每个将创建自己的OpenGL环境,然而所有上下文将共享相同的纹理对象,显示列表,着色器程序,等等,在默认情况下[1]。每个环境都有自己的状态和framebuffer。

There is always an active context (unless there are no windows). When using pyglet.app.run() for the application event loop, pyglet ensures that the correct window is the active context before dispatching the on_draw() or on_resize() events.

总有一个活跃的上下文(除非没有windows)。当使用pyglet.app.run()为应用程序事件循环,pyglet确保正确的窗口是活动上下文在调度on_draw()或on_resize()事件。

In other cases, you can explicitly set the active context with pyglet.window.Window.switch_to.

在其他情况下,您可以显式地设置与pyglet.window.Window.switch_to活跃的上下文。

<colgroup><col class="label"><col></colgroup>
| [1] | Sometimes objects and lists cannot be shared between contexts; for example, when the contexts are provided by different video devices. This will usually only occur if you explicitly select different screens driven by different devices.

有时和列表之间不能共享上下文对象;例如,当提供的上下文不同的视频设备。这将通常只发生如果你显式地选择不同的屏幕由不同的设备。

AGL, GLX and WGL

The OpenGL context itself is managed by an operating-system specific library: AGL on OS X, GLX under X11 and WGL on Windows. pyglet handles these details when a window is created, but you may need to use the functions directly (for example, to use pbuffers) or an extension function.

OpenGL环境本身是由一个操作系统特定的库管理:在OS X的榴弹炮,GLX在X11和WGL在Windows。pyglet处理这些细节在创建窗口时,但是你可能需要直接使用功能(例如,使用pbuffers)或一个扩展函数。

The modules are named pyglet.gl.agl, pyglet.gl.glx and pyglet.gl.wgl. You must only import the correct module for the running operating system:

名为pyglet.gl的模块。榴弹炮,pyglet.gl。glx pyglet.gl.wgl。你必须只导入正确的模块运行操作系统:

if sys.platform.startswith('linux'):
    from pyglet.gl.glx import *
    glxCreatePbuffer(...)
elif sys.platform == 'darwin':
    from pyglet.gl.agl import *
    aglCreatePbuffer(...)

Alternativally you can use pyglet.compat_platform to support platforms that are compatible with platforms not officially supported by pyglet. For example FreeBSD systems will appear as linux-compat in pyglet.compat_platform.

Alternativally可以使用pyglet.compat_platform支持平台,兼容平台不是由pyglet官方支持。例如FreeBSD系统将出现在pyglet.compat_platform linux-compat。

There are convenience modules for querying the version and extensions of WGL and GLX named pyglet.gl.wgl_info and pyglet.gl.glx_info, respectively. AGL does not have such a module, just query the version of OS X instead.

有方便的查询模块的版本和扩展WGL和GLX pyglet.gl命名。wgl_info pyglet.gl。分别glx_info。榴弹炮没有这样一个模块,查询版本的OS X。

If using GLX extensions, you can import pyglet.gl.glxext_arb for the registered extensions or pyglet.gl.glxext_nv for the latest nVidia extensions.

如果使用GLX扩展,您可以导入pyglet.gl。注册扩展或pyglet.gl glxext_arb。glxext_nv最新的nVidia扩展。

Similarly, if using WGL extensions, import pyglet.gl.wglext_arb or pyglet.gl.wglext_nv.

同样,如果使用WGL扩展,进口pyglet.gl。wglext_arb或pyglet.gl.wglext_nv。