122 lines
5.1 KiB
Python
122 lines
5.1 KiB
Python
'''
|
|
Graphics
|
|
========
|
|
|
|
This package assembles many low level functions used for drawing. The whole
|
|
graphics package is compatible with OpenGL ES 2.0 and has many rendering
|
|
optimizations.
|
|
|
|
The basics
|
|
----------
|
|
|
|
For drawing on a screen, you will need :
|
|
|
|
1. a :class:`~kivy.graphics.instructions.Canvas` object.
|
|
2. :class:`~kivy.graphics.instructions.Instruction` objects.
|
|
|
|
Each :class:`~kivy.uix.widget.Widget`
|
|
in Kivy already has a :class:`Canvas` by default. When you create
|
|
a widget, you can create all the instructions needed for drawing. If
|
|
`self` is your current widget, you can do::
|
|
|
|
from kivy.graphics import *
|
|
with self.canvas:
|
|
# Add a red color
|
|
Color(1., 0, 0)
|
|
|
|
# Add a rectangle
|
|
Rectangle(pos=(10, 10), size=(500, 500))
|
|
|
|
The instructions :class:`Color` and :class:`Rectangle` are automatically added
|
|
to the canvas object and will be used when the window is drawn.
|
|
|
|
.. note::
|
|
|
|
Kivy drawing instructions are not automatically relative to the position
|
|
or size of the widget. You, therefore, need to consider these factors when
|
|
drawing. In order to make your drawing instructions relative to the widget,
|
|
the instructions need either to be
|
|
declared in the :mod:`KvLang <kivy.lang>` or bound to pos and size changes.
|
|
Please see :ref:`adding_widget_background` for more detail.
|
|
|
|
GL Reloading mechanism
|
|
----------------------
|
|
|
|
.. versionadded:: 1.2.0
|
|
|
|
During the lifetime of the application, the OpenGL context might be lost. This
|
|
happens:
|
|
|
|
- when the window is resized on OS X or the Windows platform and you're
|
|
using pygame as a window provider. This is due to SDL 1.2. In the SDL 1.2
|
|
design, it needs to recreate a GL context everytime the window is
|
|
resized. This was fixed in SDL 1.3 but pygame is not yet available on it
|
|
by default.
|
|
|
|
- when Android releases the app resources: when your application goes to the
|
|
background, Android might reclaim your opengl context to give the
|
|
resource to another app. When the user switches back to your application, a
|
|
newly created gl context is given to your app.
|
|
|
|
Starting from 1.2.0, we have introduced a mechanism for reloading all the
|
|
graphics resources using the GPU: Canvas, FBO, Shader, Texture, VBO,
|
|
and VertexBatch:
|
|
|
|
- VBO and VertexBatch are constructed by our graphics instructions. We have all
|
|
the data needed to reconstruct when reloading.
|
|
|
|
- Shader: same as VBO, we store the source and values used in the
|
|
shader so we are able to recreate the vertex/fragment/program.
|
|
|
|
- Texture: if the texture has a source (an image file or atlas), the image
|
|
is reloaded from the source and reuploaded to the GPU.
|
|
|
|
You should cover these cases yourself:
|
|
|
|
- Textures without a source: if you manually created a texture and manually
|
|
blit data / a buffer to it, you must handle the reloading yourself. Check the
|
|
:doc:`api-kivy.graphics.texture` to learn how to manage that case. (The text
|
|
rendering already generates the texture and handles the reloading. You
|
|
don't need to reload text yourself.)
|
|
|
|
- FBO: if you added / removed / drew things multiple times on the FBO, we
|
|
can't reload it. We don't keep a history of the instructions put on it.
|
|
As for textures without a source, check the :doc:`api-kivy.graphics.fbo` to
|
|
learn how to manage that case.
|
|
|
|
'''
|
|
|
|
from kivy.graphics.instructions import Callback, Canvas, CanvasBase, \
|
|
ContextInstruction, Instruction, InstructionGroup, RenderContext, \
|
|
VertexInstruction
|
|
from kivy.graphics.context_instructions import BindTexture, Color, \
|
|
PushState, ChangeState, PopState, MatrixInstruction, ApplyContextMatrix, \
|
|
PopMatrix, PushMatrix, Rotate, Scale, Translate, LoadIdentity, \
|
|
UpdateNormalMatrix, gl_init_resources
|
|
from kivy.graphics.vertex_instructions import Bezier, BorderImage, Ellipse, \
|
|
GraphicException, Line, Mesh, Point, Quad, Rectangle, RoundedRectangle, \
|
|
Triangle, SmoothLine
|
|
from kivy.graphics.stencil_instructions import StencilPop, StencilPush, \
|
|
StencilUse, StencilUnUse
|
|
from kivy.graphics.gl_instructions import ClearColor, ClearBuffers
|
|
from kivy.graphics.fbo import Fbo
|
|
from kivy.graphics.scissor_instructions import ScissorPush, ScissorPop
|
|
|
|
# very hacky way to avoid pyflakes warning...
|
|
__all__ = (Bezier.__name__, BindTexture.__name__, BorderImage.__name__,
|
|
Callback.__name__, Canvas.__name__, CanvasBase.__name__,
|
|
Color.__name__, ContextInstruction.__name__,
|
|
Ellipse.__name__, Fbo.__name__, GraphicException.__name__,
|
|
Instruction.__name__, InstructionGroup.__name__,
|
|
Line.__name__, SmoothLine.__name__, MatrixInstruction.__name__,
|
|
Mesh.__name__, Point.__name__, PopMatrix.__name__,
|
|
PushMatrix.__name__, Quad.__name__, Rectangle.__name__,
|
|
RenderContext.__name__, Rotate.__name__, Scale.__name__,
|
|
StencilPop.__name__, StencilPush.__name__, StencilUse.__name__,
|
|
StencilUnUse.__name__, Translate.__name__, Triangle.__name__,
|
|
VertexInstruction.__name__, ClearColor.__name__,
|
|
ClearBuffers.__name__, gl_init_resources.__name__,
|
|
PushState.__name__, ChangeState.__name__, PopState.__name__,
|
|
ApplyContextMatrix.__name__, UpdateNormalMatrix.__name__,
|
|
LoadIdentity.__name__)
|