1 """Intuitive OpenGL wrappers.
2
3 Hacking glitter:
4 - Make sure your class uses methods and properties of its L{Context} where
5 possible instead of raw OpenGL calls; the context may cache some values or
6 trigger callbacks, and calling OpenGL directly may break functionality in
7 weird and unexpected ways. If you need to call raw GL functions, do so
8 through the {glitter.raw} wrapper. If your raw GL invocations are generic
9 enough, think about extending the L{Context} instead. Make sure to derive
10 from L{GLObject} and use C{with self._context:} where necessary if your
11 class does in any way interact directly with OpenGL. If your object is tied
12 to a single context, derive from L{GLObject}. The constructor should take
13 an optional C{context=None} parameter and pass it to L{GLObject.__init__}.
14 Also be careful to create any additional OpenGL objects within the same
15 context, preferably by passing the C{context} parameter to their
16 constructors as well.
17 - If your classes can be bound and unbound or change global state in some
18 other way, they should act as context managers. Base classes are defined in
19 the L{objects} module to help you doing it right.
20 - Provide a convenient interface wherever possible. This includes casting
21 values into the right types (e.g. to an appropriate array type using
22 L{coerce_array}), failing gracefully with descriptive error messages, and
23 adhering to conventions set by similar classes (e.g. returning C{self} from
24 C{__enter__} methods, providing a C{__call__} method to set attributes by
25 inheriting from L{StateMixin}).
26 - If your class uses enums from the L{constants} module in a public
27 interface, point a class variable of the same name to the enum so users do
28 not need to import any constants manually. Functions that accept enums
29 should cast input values into the appropriate constants using
30 C{my_enum(value)} first to ensure type safety and to enable using enum
31 constant names instead of L{EnumConstant}s.
32 - Use absolute module names when importing other glitter modules. When
33 importing from the same subpackage, use fully qualified names for the
34 module (e.g. C{from glitter.utils.objects import GLObject}); otherwise,
35 rely on the public interface of the subpackage defined in its
36 C{__init__.py} and import from the subpackage directly (e.g. C{from
37 glitter.utils import GLObject}). Do not import from the global C{glitter}
38 module directly as visibility of subpackages may change.
39 - Define the public interface of your module in C{__all__} and, if your
40 module is meant for external use, C{import *} from your module in the
41 C{__init__.py} of its parent. However, if your module has external
42 dependencies other than numpy, do not C{import *} but have the user import
43 your submodule manually.
44 - Write docstrings for epydoc (use C{@todo}, C{@note}, C{@attention},
45 C{@bug}, C{@warning} as appropriate).
46 - Write tests for nosetests (in the C{tests} directory).
47 - Write examples (in the C{examples} directory).
48
49 @todo: Use C{with self._context} for all GL calls, pass context when creating sub-objects.
50 @todo: Use caching to reduce the number of bind and unbind operations caused by C{with} statements.
51 @todo: Implement NeHe tutorials as literate example programs, add an example for PyCUDA interoperability.
52 @todo: Write documentation and tests, expecially for using multiple objects at the same time (e.g., L{Texture}s, L{Context}s).
53 @todo: Provide example datasets for the examples (volume and mesh), link to source and to index for examples.
54
55 @author: Stephan Wenger
56 @date: 2012-02-29
57 """
58
59 from glitter.arrays import *
60 from glitter.contexts import *
61 from glitter.convenience import *
62 from glitter.framebuffers import *
63 from glitter.misc import *
64 from glitter.shaders import *
65 from glitter.textures import *
66 from glitter.utils import *
67
68 from glitter.raw import set_error_check, add_logger, GLError, LoggingWrapper, NamedConstant
69