OpenGL上下文#

arcade.ArcadeContext#

class arcade.ArcadeContext(window: pyglet.window.BaseWindow, gc_mode: str = 'context_gc')[源代码]#

基类：arcade.gl.context.Context

用于Arcade的OpenGL上下文实现，具有添加的自定义功能。该上下文通常被认为是访问的 arcade.Window.ctx 。

Pyglet用户可以使用基上下文类，并可以随意扩展。

这是Arcade中低级渲染API的一部分，主要用于更高级的用途

参数

window (pyglet.window.Window) -- 侏儒窗口
gc_mode (str) -- OpenGL对象的垃圾回收模式。 auto 正是我们在python中所期望的，而 context_gc (默认)需要您调用 Context.gc() 。在不清楚哪个线程将GC对象的情况下使用多个线程时，后一种方法很有用。

classmethod activate(ctx: arcade.gl.context.Context)#: 将上下文标记为当前活动的上下文。

警告

除非你确切知道自己在做什么，否则永远不要打这个电话。

property blend_func: Tuple[int, int]#

获取或设置混合函数。这是指定如何计算源和目标像素的红色、绿色、蓝色和Alpha混合因子的元组。

支持的混合功能包括：

ZERO
ONE
SRC_COLOR
ONE_MINUS_SRC_COLOR
DST_COLOR
ONE_MINUS_DST_COLOR
SRC_ALPHA
ONE_MINUS_SRC_ALPHA
DST_ALPHA
ONE_MINUS_DST_ALPHA

# Shortcuts
DEFAULT_BLENDING     # (SRC_ALPHA, ONE_MINUS_SRC_ALPHA)
ADDITIVE_BLENDING    # (ONE, ONE)
PREMULTIPLIED_ALPHA  # (SRC_ALPHA, ONE)

这些枚举可以在 arcade.gl 模块或简单地作为上下文对象的属性。来自的原始枚举 pyglet.gl 也可以使用。

示例：：

# Using constants from the context object
ctx.blend_func = ctx.ONE, ctx.ONE
# from the gl module
from arcade import gl
ctx.blend_func = gl.ONE, gl.One

类型: 元组(源、dst)

buffer(*, data: Optional[Any] = None, reserve: int = 0, usage: str = 'static') → arcade.gl.buffer.Buffer#

创建一个OpenGL缓冲区对象。如果未提供数据，则缓冲区将包含所有零字节。

示例：

# Create 1024 byte buffer
ctx.buffer(reserve=1024)
# Create a buffer with 1000 float values using python's array.array
from array import array
ctx.buffer(data=array('f', [i for in in range(1000)])
# Create a buffer with 1000 random 32 bit floats using numpy
self.ctx.buffer(data=np.random.random(1000).astype("f4"))

这个 usage 参数使GL实现能够做出可能影响缓冲区对象性能的更智能的决策。它没有增加任何限制。如果有疑问，请跳过此参数并在优化时重新访问。结果可能因供应商/驱动程序不同而不同，或者可能没有任何影响。

可用值包括以下含义：

stream
    The data contents will be modified once and used at most a few times.
static
    The data contents will be modified once and used many times.
dynamic
    The data contents will be modified repeatedly and used many times.

参数

data (Any) -- 缓冲区数据，这可以是 bytes 或支持缓冲协议的对象。
reserve (int) -- 保留的字节数
usage (str) -- 缓冲区使用率。“静态”、“动态”或“流”

返回类型

Buffer

compute_shader(*, source: str) → arcade.gl.compute_shader.ComputeShader#

创建计算着色器。

参数: source (str) -- GLSL源代码

copy_framebuffer(src: arcade.gl.framebuffer.Framebuffer, dst: arcade.gl.framebuffer.Framebuffer)#

将一个帧缓冲区复制/b到另一个帧缓冲区。

此操作有许多限制，以确保其跨不同平台和驱动程序工作：

源和目标帧缓冲区的大小必须相同
附件的格式必须相同
只能对源帧缓冲区进行多重采样
帧缓冲区不能有整数附件

参数

src (Framebuffer) -- 要从中进行复制的帧缓冲区
dst (Framebuffer) -- 我们复制到的帧缓冲区

property default_atlas: arcade.texture_atlas.TextureAtlas#

默认纹理贴图集。这是在初始化Arcade时创建的。所有精灵列表都将使用此地图集，除非在 arcade.SpriteList 构造函数。

类型: TextureAtlas

depth_texture(size: Tuple[int, int], *, data=None) → arcade.gl.texture.Texture#

创建2D深度纹理。中的深度附件。 Framebuffer 。

参数

size (Tuple[int, int]) -- 纹理的大小
data (Any) -- 纹理数据(可选)。可以是字节，也可以是支持缓冲区协议的对象。

disable(*args)#

禁用一个或多个上下文标志：：

# Single flag
ctx.disable(ctx.BLEND)
# Multiple flags
ctx.disable(ctx.DEPTH_TEST, ctx.CULL_FACE)

enable(*flags)#

启用一个或多个上下文标志：

# Single flag
ctx.enable(ctx.BLEND)
# Multiple flags
ctx.enable(ctx.DEPTH_TEST, ctx.CULL_FACE)

enable_only(*args)#

仅启用一些标志。这将禁用所有其他标志。这是一种简单的方法，可以确保上下文标志状态不会在代码库的其他部分中徘徊：

# Ensure all flags are disabled (enable no flags)
ctx.enable_only()
# Make sure only blending is enabled
ctx.enable_only(ctx.BLEND)
# Make sure only depth test and culling is enabled
ctx.enable_only(ctx.DEPTH_TEST, ctx.CULL_FACE)        

enabled(*flags)#

临时更改启用标志。

最初启用的标志将保持启用状态。只有新启用的标志在退出上下文时才会被反转。

示例：：

with ctx.enabled(ctx.BLEND, ctx.CULL_FACE):
    # Render something

enabled_only(*flags)#

临时更改启用标志。

只有在上下文中启用了提供的标志。当退出上下文时，旧标志将被恢复。

示例：：

with ctx.enabled_only(ctx.BLEND, ctx.CULL_FACE):
    # Render something

property error: Optional[str]#

检查OpenGL错误

返回发生的错误的字符串表示形式，或者 None 没有发生任何错误。

示例：：

err = ctx.error
if err:
    raise RuntimeError("OpenGL error: {err}")

类型: 应力

property fbo: arcade.gl.framebuffer.Framebuffer#

获取当前活动的帧缓冲区。此属性为只读

类型: arcade.gl.Framebuffer

finish() → None#

等待所有OpenGL渲染命令完成。

此函数实际上将停止，直到完成所有工作，并且可能会对性能造成严重影响。

flush() → None#: 建议驱动程序执行所有排队的绘图调用，即使队列还未满。这不是阻止呼叫，只是一个建议。当我们没有其他东西可以渲染时，这可能会用于加速。

framebuffer(*, color_attachments: Optional[Union[arcade.gl.texture.Texture, List[arcade.gl.texture.Texture]]] = None, depth_attachment: Optional[arcade.gl.texture.Texture] = None) → arcade.gl.framebuffer.Framebuffer#

创建帧缓冲区。

参数

color_attachments (List[arcade.gl.Texture]) -- 要渲染到的纹理列表
depth_attachment (arcade.gl.Texture) -- 深度纹理

返回类型

Framebuffer

gc() → int#

为此上下文运行OpenGL对象的垃圾回收。仅在以下情况下才需要此功能 gc_mode 是 context_gc 。

返回: 被破坏的资源数量
返回类型: int

property gc_mode: str#

设置OpenGL资源的垃圾收集模式。支持的模式包括：

# Default:
# Defer garbage collection until ctx.gc() is called
# This can be useful to enforce the main thread to
# run garbage collection of opengl resources
ctx.gc_mode = "context_gc"

# Auto collect is similar to python garbage collection.
# This is a risky mode. Know what you are doing before using this.
ctx.gc_mode = "auto"

geometry(content: Optional[Sequence[arcade.gl.types.BufferDescription]] = None, index_buffer: Optional[arcade.gl.buffer.Buffer] = None, mode: Optional[int] = None, index_element_size: int = 4)#

创建Geomtry实例。这是Arcade版本的顶点数组，为用户增加了很多便利。几何体对象相当轻。它们主要负责将缓冲区输入自动映射到着色器，并提供渲染或处理该几何体的各种方法。

只要着色器使用一个或多个输入属性，就可以使用不同的程序渲染相同的几何体。这意味着具有位置和颜色的几何体只能通过使用位置的程序进行渲染。我们将自动映射所需的内容，并在内部缓存这些映射以提高性能。

简而言之，几何体对象是一个灯光对象，它描述缓冲区包含的内容并自动与着色器/程序协商。这在OpenGL中是一个非常复杂的字段，因此Geometry对象可以节省大量时间，并极大地降低代码的复杂性。

几何体还提供支持以下内容的渲染方法：

使用和不使用索引缓冲区渲染几何图形
使用实例化渲染几何体。可以提供每个实例的缓冲区，也可以使用 gl_InstanceID 在着色器中。
运行写入缓冲区而不是屏幕的变换反馈着色器。这可以写入一个或多个缓冲区。
使用间接渲染渲染几何体。这意味着将多个网格打包到同一缓冲区中并批量绘制它们。

示例：

# Single buffer geometry with a vec2 vertex position attribute
ctx.geometry([BufferDescription(buffer, '2f', ["in_vert"])], mode=ctx.TRIANGLES)

# Single interlaved buffer with two attributes. A vec2 position and vec2 velocity
ctx.geometry([
        BufferDescription(buffer, '2f 2f', ["in_vert", "in_velocity"])
    ],
    mode=ctx.POINTS,
)

# Geometry with index buffer
ctx.geometry(
    [BufferDescription(buffer, '2f', ["in_vert"])],
    index_buffer=ibo,
    mode=ctx.TRIANGLES,
)

# Separate buffers
ctx.geometry([
        BufferDescription(buffer_pos, '2f', ["in_vert"])
        BufferDescription(buffer_vel, '2f', ["in_velocity"])
    ],
    mode=ctx.POINTS,
)

# Providing per-instance data for instancing
ctx.geometry([
        BufferDescription(buffer_pos, '2f', ["in_vert"])
        BufferDescription(buffer_instance_pos, '2f', ["in_offset"], instanced=True)
    ],
    mode=ctx.POINTS,
)

参数

content (list) -- 列表： BufferDescription (可选)
index_buffer (Buffer) -- 索引/元素缓冲区(可选)
mode (int) -- 默认绘图模式(可选)
mode -- 默认绘图模式(可选)
index_element_size (int) -- 索引缓冲区中单个索引/元素的字节大小。换句话说，索引缓冲区可以是8位、16位或32位整数。可以是1、2或4(8、16或32位无符号整数)

property gl_version: Tuple[int, int]#

两个组件元组形式的OpenGL版本。这是驱动程序中报告的OpenGL版本，可能比您要求的版本更高。

类型: 元组(主要、次要)版本

property info: arcade.gl.context.Limits#

获取此上下文的Limits对象，该对象包含有关硬件/驱动程序限制的信息和其他上下文信息。

示例：：

>> ctx.info.MAX_TEXTURE_SIZE
(16384, 16384)
>> ctx.info.VENDOR
NVIDIA Corporation
>> ctx.info.RENDERER
NVIDIA GeForce RTX 2080 SUPER/PCIe/SSE2

is_enabled(flag) → bool#

检查是否启用了上下文标志

类型: 布尔尔

property limits: arcade.gl.context.Limits#

获取此上下文的Limits对象，该对象包含有关硬件/驱动程序限制的信息和其他上下文信息。

警告

这是一个旧的别名 info 并且只是为了向后兼容。

示例：：

>> ctx.limits.MAX_TEXTURE_SIZE
(16384, 16384)
>> ctx.limits.VENDOR
NVIDIA Corporation
>> ctx.limits.RENDERER
NVIDIA GeForce RTX 2080 SUPER/PCIe/SSE2

load_compute_shader(path: Union[str, pathlib.Path]) → arcade.gl.compute_shader.ComputeShader[源代码]#

从文件加载计算着色器。此方法支持资源句柄。

示例：：

ctx.load_compute_shader(":shader:compute/do_work.glsl")

参数: path (Union[str,pathlib.Path]) -- 纹理路径

load_program(*, vertex_shader: Union[str, pathlib.Path], fragment_shader: Optional[Union[str, pathlib.Path]] = None, geometry_shader: Optional[Union[str, pathlib.Path]] = None, tess_control_shader: Optional[Union[str, pathlib.Path]] = None, tess_evaluation_shader: Optional[Union[str, pathlib.Path]] = None, defines: Optional[dict] = None) → arcade.gl.program.Program[源代码]#

在给定包含顶点着色器和片段着色器的文件名的情况下创建新程序。请注意，在加载变换着色器时，碎片着色器和几何体着色器是可选的。

此方法还支持 :resources: 前缀。建议使用绝对路径，但不是必需的。

示例：：

# The most common use case if having a vertex and fragment shader
program = window.ctx.load_program(
    vertex_shader="vert.glsl",
    fragment_shader="frag.glsl",
)

参数

vertex_shader (Union[str,pathlib.Path]) -- 顶点着色器的路径
fragment_shader (Union[str,pathlib.Path]) -- 片段着色器的路径(可选)
geometry_shader (Union[str,pathlib.Path]) -- 几何体着色器的路径(可选)
defines (dict) -- 代替品 #define 源代码中的值
tess_control_shader (Union[str,pathlib.Path]) -- 细分控制着色器
tess_evaluation_shader (Union[str,pathlib.Path]) -- 细分求值明暗器

load_texture(path: Union[str, pathlib.Path], *, flip: bool = True, build_mipmaps: bool = False) → arcade.gl.texture.Texture[源代码]#

加载并创建OpenGL 2D纹理。目前，为简单起见，所有纹理都转换为RGBA。

示例：：

# Load a texture in current working directory
texture = window.ctx.load_texture("background.png")
# Load a texture using Arcade resource handle
texture = window.ctx.load_texture(":textures:background.png")

参数

path (Union[str,pathlib.Path]) -- 纹理路径
flip (bool) -- 将图像颠倒
build_mipmaps (bool) -- 为纹理构建mipmap

objects: Deque[Any]#: 当GC_MODE为“CONTEXT_GC”时，收集到GC的对象。这可以在调试期间使用。

property patch_vertices: int#

获取或设置将用于组成单个面片基本体的顶点数。面片基本体由细分控制着色器(如果存在)使用，并随后用于细分。

类型: 集成

property point_size: float#

设置或获取磅大小。默认值为 1.0 。

点大小更改渲染点的像素大小。最小值和最大值受以下限制 POINT_SIZE_RANGE 。该值通常至少 (1, 100) ，但这取决于驱动程序/供应商。

如果需要可变磅大小，您可以启用 PROGRAM_POINT_SIZE 并写信给 gl_PointSize 在顶点或几何体着色器中。

注解

使用几何体着色器从点创建三角形条带通常是渲染大点的更安全的方法，因为您没有任何大小限制。

property primitive_restart_index: int#

获取或设置基元重新启动索引。默认值为 -1 。

可以在索引缓冲区中使用原语重新启动索引来重新启动原语。例如，当您使用三角形条带或线条并希望在同一缓冲区/绘制调用中开始一个新的条带时，这是很有用的。

program(*, vertex_shader: str, fragment_shader: Optional[str] = None, geometry_shader: Optional[str] = None, tess_control_shader: Optional[str] = None, tess_evaluation_shader: Optional[str] = None, defines: Optional[Dict[str, str]] = None, varyings: Optional[Sequence[str]] = None, varyings_capture_mode: str = 'interleaved') → arcade.gl.program.Program#

创建 Program 给定顶点、碎片和几何体着色器。

参数

vertex_shader (str) -- 顶点着色器源
fragment_shader (str) -- 片段着色器源(可选)
geometry_shader (str) -- 几何体着色器源(可选)
tess_control_shader (str) -- 细分控制着色器源(可选)
tess_evaluation_shader (str) -- 细分求值明暗器源(可选)
defines (dict) -- 替换#定义源中的值(可选)
varyings (Optional[Sequence[str]]) -- 变换着色器中的输出属性的名称。这通常是不必要的，因为我们会自动检测它们，而是一些我们无法检测到的更复杂的外部结构。
varyings_capture_mode (str) -- 转换的捕获模式。 "interleaved" 意味着所有输出属性将写入单个缓冲区。 "separate" 意味着每个OUT属性将被写入单独的缓冲区。根据这些设置， transform() 方法将接受单个缓冲区或缓冲区列表。

返回类型

Program

property projection_2d: Tuple[float, float, float, float]#

获取或设置arcade的全局正交投影。

此投影由精灵和形状使用，并由四个浮点表示： (left, right, bottom, top)

类型: 元组 [浮动，浮动]

property projection_2d_matrix: pyglet.math.Mat4#

获取当前投影矩阵。此4x4浮点32矩阵是在设置 projection_2d 。

类型: pyglet.math.Mat4

pyglet_rendering()[源代码]#

用于侏儒渲染的上下文管理器。因为arcade和pyglet需要稍微不同的状态，所以我们需要一些初始化和清理。

示例：

with window.ctx.pyglet_rendering():
    # Draw with pyglet here

query(*, samples=True, time=True, primitives=True)#

在OpenGL中创建一个用于测量渲染调用的Query对象。

参数

samples (bool) -- 收集书面样本
time (bool) -- 测量渲染持续时间
primitives (bool) -- 收集发出的基元数量

返回类型

Query

reset() → None[源代码]#: 重置上下文标志和其他状态。这主要用于单元测试。

property scissor: Optional[Tuple[int, int, int, int]]#

获取或设置活动帧缓冲区的剪贴框。这是一条快捷方式 scissor() 。

默认情况下，剪裁框处于禁用状态，不起作用，初始值为 None 。设置值时启用剪贴框，设置为时禁用剪贴框 None 。

示例：：

# Set and enable scissor box only drawing
# in a 100 x 100 pixel lower left area
ctx.scissor = 0, 0, 100, 100
# Disable scissoring
ctx.scissor = None

类型: 元组(x，y，宽度，高度)

property screen: arcade.gl.framebuffer.Framebuffer#

窗口的帧缓冲区。

类型: Framebuffer

property stats: arcade.gl.context.ContextStats#

获取包含有关创建和销毁OpenGL对象的运行时信息的Stats实例。

示例：：

>> ctx.limits.MAX_TEXTURE_SIZE
(16384, 16384)
>> ctx.limits.VENDOR
NVIDIA Corporation
>> ctx.limits.RENDERER
NVIDIA GeForce RTX 2080 SUPER/PCIe/SSE2

texture(size: Tuple[int, int], *, components: int = 4, dtype: str = 'f1', data: Optional[Any] = None, wrap_x: Optional[ctypes.c_uint] = None, wrap_y: Optional[ctypes.c_uint] = None, filter: Optional[Tuple[ctypes.c_uint, ctypes.c_uint]] = None, samples: int = 0) → arcade.gl.texture.Texture#

创建2D纹理。

换行模式： GL_REPEAT ， GL_MIRRORED_REPEAT ， GL_CLAMP_TO_EDGE ， GL_CLAMP_TO_BORDER

缩小滤镜： GL_NEAREST ， GL_LINEAR ， GL_NEAREST_MIPMAP_NEAREST ， GL_LINEAR_MIPMAP_NEAREST GL_NEAREST_MIPMAP_LINEAR ， GL_LINEAR_MIPMAP_LINEAR

放大滤镜： GL_NEAREST ， GL_LINEAR

参数

size (Tuple[int, int]) -- 纹理的大小
components (int) -- 组件数量(1：R、2：RG、3：RGB、4：RGBA)
dtype (str) -- 各组件的数据类型：f1、f2、f4/i1、i2、i4/u1、u2、u4
data (Any) -- 纹理数据(可选)。可以是字节，也可以是支持缓冲区协议的对象。
wrap_x (GLenum) -- 纹理在x方向上的换行方式
wrap_y (GLenum) -- 纹理在y方向上的换行方式
filter (Tuple[GLenum,GLenum]) -- 缩小和放大滤镜
samples (int) -- 为大于0的值创建多采样纹理

property viewport: Tuple[int, int, int, int]#

获取或设置当前活动帧缓冲区的视区。该视口只描述OpenGL应该渲染到的屏幕像素。通常它是窗口的帧缓冲区的大小：：

# 4:3 screen
ctx.viewport = 0, 0, 800, 600
# 1080p
ctx.viewport = 0, 0, 1920, 1080
# Using the current framebuffer size
ctx.viewport = 0, 0, *ctx.screen.size

类型: 元组(x，y，宽度，高度)

property window: pyglet.window.BaseWindow#

此上下文所属的窗口。

类型: pyglet.Window