ic
/
magnum-bindings
6
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

doc: switch to explicit :ref: as default roles don't work well.

pull/10/head
Vladimír Vondruš 6 years ago
parent
fe559e69bd
commit
be5ffdd916
12 changed files with 214 additions and 196 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 56
      doc/python/corrade.containers.rst
  2. 6
      doc/python/corrade.pluginmanager.rst
  3. 2
      doc/python/corrade.rst
  4. 39
      doc/python/magnum.gl.rst
  5. 36
      doc/python/magnum.math.rst
  6. 65
      doc/python/magnum.rst
  7. 32
      doc/python/magnum.shaders.rst
  8. 80
      doc/python/magnum.trade.rst
  9. 51
      doc/python/pages/api-conventions.rst
  10. 6
      doc/python/pages/building.rst
  11. 27
      doc/python/pages/changelog.rst
  12. 10
      doc/python/pages/index.rst

56
doc/python/corrade.containers.rst
Unescape View File

@ -30,11 +30,11 @@
Provides one-dimensional tightly packed view on a memory range. Convertible Provides one-dimensional tightly packed view on a memory range. Convertible
both from and to Python objects supporting the Buffer Protocol, with one both from and to Python objects supporting the Buffer Protocol, with one
dimension and stride of :py:`1`. See `StridedArrayView1D` and others for dimension and stride of :py:`1`. See :ref:`StridedArrayView1D` and others
more generic views. `ArrayView` is immutable, see `MutableArrayView` for for more generic views. :ref:`ArrayView` is immutable, see
the mutable alterantive. All slicing operations are supported, specifying a :ref:`MutableArrayView` for the mutable alterantive. All slicing operations
non-trivial stride will return `StridedArrayView1D` instead of `ArrayView`. are supported, specifying a non-trivial stride will return
Example usage: :ref:`StridedArrayView1D` instead of :ref:`ArrayView`. Example usage:
.. code:: pycon .. code:: pycon
@ -49,10 +49,10 @@
========================================== ==========================================
Unlike in C++, the view keeps a reference to the original memory owner Unlike in C++, the view keeps a reference to the original memory owner
object in the `owner` field, meaning that calling :py:`del` on the original object in the :ref:`owner` field, meaning that calling :py:`del` on the
object will *not* invalidate the view. Slicing a view creates a new view original object will *not* invalidate the view. Slicing a view creates a
referencing the same original object, without any dependency on the new view referencing the same original object, without any dependency on
previous view. That means a long chained slicing operation will not cause the previous view. That means a long chained slicing operation will not cause
increased memory usage. increased memory usage.
.. code:: pycon .. code:: pycon
@ -62,53 +62,55 @@
>>> b[1:4][:-1].owner is a >>> b[1:4][:-1].owner is a
True True
The `owner` is :py:`None` if the view is empty. The :py:`owner` is :py:`None` if the view is empty.
`Comparison to Python's memoryview`_ `Comparison to Python's memoryview`_
==================================== ====================================
The `ArrayView` class is equivalent to one-dimensional `memoryview` with a The :ref:`ArrayView` class is equivalent to one-dimensional
stride of :py:`1`. For multiple dimensions and non-trivial strides, :ref:`memoryview` with a stride of :py:`1`. For multiple dimensions and
`StridedArrayView1D` and friends provide a superset of `memoryview` non-trivial strides, :ref:`StridedArrayView1D` and friends provide a
features. superset of :ref:`memoryview` features.
.. py:class:: corrade.containers.MutableArrayView .. py:class:: corrade.containers.MutableArrayView
Equivalent to `ArrayView`, but implementing `__setitem__()` as well. Equivalent to :ref:`ArrayView`, but implementing :ref:`__setitem__()` as
well.
.. py:class:: corrade.containers.StridedArrayView1D .. py:class:: corrade.containers.StridedArrayView1D
Provides one-dimensional read-only view on a memory range with custom Provides one-dimensional read-only view on a memory range with custom
stride values. See `StridedArrayView2D`, `StridedArrayView3D`, stride values. See :ref:`StridedArrayView2D`, :ref:`StridedArrayView3D`,
`MutableStridedArrayView1D` and others for multi-dimensional and mutable :ref:`MutableStridedArrayView1D` and others for multi-dimensional and
equivalents. mutable equivalents.
`Comparison to Python's memoryview`_ `Comparison to Python's memoryview`_
==================================== ====================================
The `StridedArrayView1D` and its multi-dimensional variants are equivalent The :ref:`StridedArrayView1D` and its multi-dimensional variants are
to any `memoryview`, but additionally supporting multi-dimensional slicing equivalent to any :ref:`memoryview`, but additionally supporting
as well (which raises `NotImplementedError` in Py3.7 `memoryview`). multi-dimensional slicing as well (which raises :ref:`NotImplementedError`
in Py3.7 :ref:`memoryview`).
.. py:class:: corrade.containers.MutableStridedArrayView1D .. py:class:: corrade.containers.MutableStridedArrayView1D
Equivalent to `StridedArrayView1D`, but implementing `__setitem__()` as Equivalent to :ref:`StridedArrayView1D`, but implementing
well. :ref:`__setitem__()` as well.
.. py:class:: corrade.containers.StridedArrayView2D .. py:class:: corrade.containers.StridedArrayView2D
See `StridedArrayView1D` for more information. See :ref:`StridedArrayView1D` for more information.
.. py:class:: corrade.containers.MutableStridedArrayView2D .. py:class:: corrade.containers.MutableStridedArrayView2D
See `StridedArrayView1D` and `MutableStridedArrayView1D` for more See :ref:`StridedArrayView1D` and :ref:`MutableStridedArrayView1D` for more
information. information.
.. py:class:: corrade.containers.StridedArrayView3D .. py:class:: corrade.containers.StridedArrayView3D
See `StridedArrayView1D` for more information. See :ref:`StridedArrayView1D` for more information.
.. py:class:: corrade.containers.MutableStridedArrayView3D .. py:class:: corrade.containers.MutableStridedArrayView3D
See `StridedArrayView1D` and `MutableStridedArrayView1D` for more See :ref:`StridedArrayView1D` and :ref:`MutableStridedArrayView1D` for more
information. information.

6
doc/python/corrade.pluginmanager.rst
Unescape View File

@ -28,9 +28,9 @@
.. py:function:: corrade.pluginmanager.AbstractManager.load .. py:function:: corrade.pluginmanager.AbstractManager.load
:raise RuntimeError: When loading fails :raise RuntimeError: When loading fails
:return: `LoadState.LOADED`, possibly combined with other flags such as :return: :ref:`LoadState.LOADED`, possibly combined with other flags such
`LoadState.STATIC` as :ref:`LoadState.STATIC`
.. py:function:: corrade.pluginmanager.AbstractManager.unload .. py:function:: corrade.pluginmanager.AbstractManager.unload
:raise RuntimeError: When unloading fails :raise RuntimeError: When unloading fails
:return: Either `LoadState.NOT_LOADED` or `LoadState.STATIC` :return: Either :ref:`LoadState.NOT_LOADED` or :ref:`LoadState.STATIC`

2
doc/python/corrade.rst
Unescape View File

@ -35,8 +35,6 @@
.. doctest setup .. doctest setup
>>> from corrade import * >>> from corrade import *
.. default-role:: ref
.. py:module:: corrade .. py:module:: corrade
:data BUILD_STATIC: Static library build :data BUILD_STATIC: Static library build
:data BUILD_MULTITHREADED: Multi-threaded build :data BUILD_MULTITHREADED: Multi-threaded build

39
doc/python/magnum.gl.rst
Unescape View File

@ -26,8 +26,7 @@
.. py:module:: magnum.gl .. py:module:: magnum.gl
:data default_framebuffer: Default framebuffer instance :data default_framebuffer: Default framebuffer instance
TODO: remove this once m.css stops ignoring the first caption on a page :TODO: remove this line once m.css stops ignoring first caption on a page
#######################################################################
`NoCreate constructors`_ `NoCreate constructors`_
======================== ========================
@ -50,50 +49,50 @@
.. py:class:: magnum.gl.Mesh .. py:class:: magnum.gl.Mesh
TODO: remove this once m.css stops ignoring the first caption on a page :TODO: remove this line once m.css stops ignoring first caption on a page
#######################################################################
`Buffer ownership and reference counting`_ `Buffer ownership and reference counting`_
========================================== ==========================================
Unlike in C++, where a :dox:`GL::Buffer` is either :dox:`std::move()`\ d Unlike in C++, where a :dox:`GL::Buffer` is either :dox:`std::move()`\ d
into the mesh or referenced externally (with the user being responsible for into the mesh or referenced externally (with the user being responsible for
its lifetime), the `gl.Mesh` object keeps references to all buffers added its lifetime), the :ref:`gl.Mesh` object keeps references to all buffers
to it. added to it.
.. py:property:: magnum.gl.Mesh.primitive .. py:property:: magnum.gl.Mesh.primitive
While querying this property will always give back a `gl.MeshPrimitive`, While querying this property will always give back a :ref:`gl.MeshPrimitive`,
this property can be set using either `magnum.MeshPrimitive` or this property can be set using either :ref:`magnum.MeshPrimitive` or
`gl.MeshPrimitive`, similarly to how the overloaded :ref:`gl.MeshPrimitive`, similarly to how the overloaded
:dox:`GL::Mesh::setPrimitive()` works. :dox:`GL::Mesh::setPrimitive()` works.
.. py:property:: magnum.gl.Texture1D.minification_filter .. py:property:: magnum.gl.Texture1D.minification_filter
See `Texture2D.minification_filter` for more information. See :ref:`Texture2D.minification_filter` for more information.
.. py:property:: magnum.gl.Texture2D.minification_filter .. py:property:: magnum.gl.Texture2D.minification_filter
This property accepts either a tuple of `magnum.SamplerFilter` / This property accepts either a tuple of :ref:`magnum.SamplerFilter` /
`gl.SamplerFilter` and `magnum.SamplerMipmap` / `gl.SamplerMipmap` values :ref:`gl.SamplerFilter` and :ref:`magnum.SamplerMipmap` /
or just `magnum.SamplerFilter` / `gl.SamplerFilter` alone in which case :ref:`gl.SamplerMipmap` values or just :ref:`magnum.SamplerFilter` / :ref:`gl.SamplerFilter` alone in which case :ref:`gl.SamplerMipmap.BASE`
`gl.SamplerMipmap.BASE` will be used implicitly; similarly to how the will be used implicitly; similarly to how the overloaded
overloaded :dox:`GL::Texture::setMinificationFilter()` works. :dox:`GL::Texture::setMinificationFilter()` works.
.. py:property:: magnum.gl.Texture3D.minification_filter .. py:property:: magnum.gl.Texture3D.minification_filter
See `Texture2D.minification_filter` for more information. See :ref:`Texture2D.minification_filter` for more information.
.. py:property:: magnum.gl.Texture1D.magnification_filter .. py:property:: magnum.gl.Texture1D.magnification_filter
See `Texture2D.magnification_filter` for more information. See :ref:`Texture2D.magnification_filter` for more information.
.. py:property:: magnum.gl.Texture2D.magnification_filter .. py:property:: magnum.gl.Texture2D.magnification_filter
This property accepts either `magnum.SamplerFilter` or `gl.SamplerFilter`, This property accepts either :ref:`magnum.SamplerFilter` or
similarly to how the overloaded :dox:`GL::Texture::setMagnificationFilter()` :ref:`gl.SamplerFilter`, similarly to how the overloaded
:dox:`GL::Texture::setMagnificationFilter()`
works. works.
.. py:property:: magnum.gl.Texture3D.magnification_filter .. py:property:: magnum.gl.Texture3D.magnification_filter
See `Texture2D.magnification_filter` for more information. See :ref:`Texture2D.magnification_filter` for more information.

36
doc/python/magnum.math.rst
Unescape View File

@ -38,7 +38,7 @@
In the C++ API, math types are commonly used via :cpp:`typedef`\ s in the In the C++ API, math types are commonly used via :cpp:`typedef`\ s in the
root namespace, only library-level generic code uses things like root namespace, only library-level generic code uses things like
:dox:`Math::Vector<size, T> <Math::Vector>`. Since Python doesn't have :dox:`Math::Vector<size, T> <Math::Vector>`. Since Python doesn't have
templates or generics, there are no generic variants in the `magnum.math` templates or generics, there are no generic variants in the :ref:`magnum.math`
module, all the concrete types are in the root module with the same names module, all the concrete types are in the root module with the same names
as in the C++ variant. as in the C++ variant.
@ -82,7 +82,7 @@
As shown above, all math types are constructible from a (nested) tuple of As shown above, all math types are constructible from a (nested) tuple of
matching type, matching the convenience of C++11 uniform initializers. As matching type, matching the convenience of C++11 uniform initializers. As
another example, a function accepting a `Quaternion` will accept a another example, a function accepting a :ref:`Quaternion` will accept a
:py:`((x, y, z), w)` tuple as well, but not :py:`(x, y, z, w)`, as that is :py:`((x, y, z), w)` tuple as well, but not :py:`(x, y, z, w)`, as that is
not convertible to a pair of a three-component vector and a scalar. not convertible to a pair of a three-component vector and a scalar.
@ -94,11 +94,11 @@
Currently, doing :py:`from magnum import math` will bring in the Currently, doing :py:`from magnum import math` will bring in the
Magnum's math module which at the moment *does not* contain the Magnum's math module which at the moment *does not* contain the
well-known Python APIs and constants. In particular, calling well-known Python APIs and constants. In particular, calling
`magnum.math.sin()` expects an explicit `Deg` / `Rad` type, while :ref:`magnum.math.sin()` expects an explicit :ref:`Deg` / :ref:`Rad`
Python's `math.sin()` doesn't. This will get resolved either by making type, while Python's :ref:`math.sin()` doesn't. This will get resolved
all Python overloads present in the same module or giving the user an either by making all Python overloads present in the same module or
option whether to use Magnum math or Python math. For now, to avoid giving the user an option whether to use Magnum math or Python math.
confusion, do for example this: For now, to avoid confusion, do for example this:
.. code:: pycon .. code:: pycon
@ -114,8 +114,8 @@
Since Python doesn't really differentiate between 32bit and 64bit doubles, Since Python doesn't really differentiate between 32bit and 64bit doubles,
all *scalar* functions taking or returning a floating-point type (such as all *scalar* functions taking or returning a floating-point type (such as
the `Deg` / `Rad` types, `math.pi <magnum.math.pi>` or the :ref:`Deg` / :ref:`Rad` types, :ref:`math.pi <magnum.math.pi>` or
`math.sin <magnum.math.sin()>`) use the :cpp:`double` variant of the :ref:`math.sin <magnum.math.sin()>`) use the :cpp:`double` variant of the
underlying C++ API --- the extra arithmetic cost is negligible to the underlying C++ API --- the extra arithmetic cost is negligible to the
Python-to-C++ function call overhead. Python-to-C++ function call overhead.
@ -128,7 +128,7 @@
All vector classes are implicitly convertible from a tuple of correct size All vector classes are implicitly convertible from a tuple of correct size
and type as well as from/to type implementing the buffer protocol, and and type as well as from/to type implementing the buffer protocol, and
these can be also converted back to lists using list comprehensions. This these can be also converted back to lists using list comprehensions. This
makes them fully compatible with `numpy.ndarray`, so the following makes them fully compatible with :ref:`numpy.ndarray`, so the following
expressions are completely valid: expressions are completely valid:
.. ..
@ -214,11 +214,11 @@
`Static constructors and instance method / property overloads`_ `Static constructors and instance method / property overloads`_
--------------------------------------------------------------- ---------------------------------------------------------------
While not common in Python, the `Matrix4.scaling()` / `Matrix4.rotation()` While not common in Python, the :ref:`Matrix4.scaling()` /
methods mimic the C++ equivalent --- calling :py:`Matrix4.scaling(vec)` :ref:`Matrix4.rotation()` methods mimic the C++ equivalent --- calling
will return a scaling matrix, while :py:`mat.scaling()` returns the 3x3 :py:`Matrix4.scaling(vec)` will return a scaling matrix, while
scaling part of the matrix. With `Matrix4.translation`, it's a bit more :py:`mat.scaling()` returns the 3x3 scaling part of the matrix. With
involved --- calling :py:`Matrix4.translation(vec)` will return a :ref:`Matrix4.translation`, it's a bit more involved --- calling
translation matrix, while :py:`mat.translation` is a read-write property :py:`Matrix4.translation(vec)` will return a translation matrix, while
accessing the fourth column of the matrix. Similarly for the `Matrix3` :py:`mat.translation` is a read-write property accessing the fourth column
class. of the matrix. Similarly for the :ref:`Matrix3` class.

65
doc/python/magnum.rst
Unescape View File

@ -38,88 +38,89 @@
.. py:class:: magnum.Image1D .. py:class:: magnum.Image1D
See `Image2D` for more information. See :ref:`Image2D` for more information.
.. py:class:: magnum.Image2D .. py:class:: magnum.Image2D
An owning counterpart to `ImageView2D` / `MutableImageView2D`. Holds its An owning counterpart to :ref:`ImageView2D` / :ref:`MutableImageView2D`.
own data buffer, thus doesn't have an equivalent to `ImageView2D.owner`. Holds its own data buffer, thus doesn't have an equivalent to
Implicitly convertible to `ImageView2D` / `MutableImageView2D`, so all APIs :ref:`ImageView2D.owner`. Implicitly convertible to :ref:`ImageView2D` /
consuming image views work with this type as well. :ref:`MutableImageView2D`, so all APIs consuming image views work with this
type as well.
.. py:class:: magnum.Image3D .. py:class:: magnum.Image3D
See `Image2D` for more information. See :ref:`Image2D` for more information.
.. py:class:: magnum.ImageView1D .. py:class:: magnum.ImageView1D
See `ImageView2D` for more information. See :ref:`ImageView2D` for more information.
.. py:class:: magnum.ImageView2D .. py:class:: magnum.ImageView2D
TODO: remove this once m.css stops ignoring the first caption on a page :TODO: remove this line once m.css stops ignoring first caption on a page
#######################################################################
`Memory ownership and reference counting`_ `Memory ownership and reference counting`_
========================================== ==========================================
Similarly to `corrade.containers.ArrayView` (and unlike in C++), the view Similarly to :ref:`corrade.containers.ArrayView` (and unlike in C++), the
keeps a reference to the original memory owner object in the `owner` field, view keeps a reference to the original memory owner object in the
meaning that calling :py:`del` on the original object will *not* invalidate :ref:`owner` field, meaning that calling :py:`del` on the original object
the view. Slicing a view creates a new view referencing the same original will *not* invalidate the view. Slicing a view creates a new view
object, without any dependency on the previous view. That means a long referencing the same original object, without any dependency on the
chained slicing operation will not cause increased memory usage. previous view. That means a long chained slicing operation will not cause
increased memory usage.
The `owner` is :py:`None` if the view is empty. The :ref:`owner` is :py:`None` if the view is empty.
.. py:class:: magnum.ImageView3D .. py:class:: magnum.ImageView3D
See `ImageView2D` for more information. See :ref:`ImageView2D` for more information.
.. py:class:: magnum.MutableImageView1D .. py:class:: magnum.MutableImageView1D
See `ImageView2D` for more information. See :ref:`ImageView2D` for more information.
.. py:class:: magnum.MutableImageView2D .. py:class:: magnum.MutableImageView2D
See `ImageView2D` for more information. See :ref:`ImageView2D` for more information.
.. py:class:: magnum.MutableImageView3D .. py:class:: magnum.MutableImageView3D
See `ImageView2D` for more information. See :ref:`ImageView2D` for more information.
.. py:function:: magnum.ImageView1D.__init__(self, arg0: magnum.ImageView1D) .. py:function:: magnum.ImageView1D.__init__(self, arg0: magnum.ImageView1D)
:raise RuntimeError: If `trade.ImageData1D.is_compressed` is :py:`True` :raise RuntimeError: If :ref:`trade.ImageData1D.is_compressed` is :py:`True`
This function is used to implement implicit conversion from This function is used to implement implicit conversion from
`trade.ImageData1D` in the `trade` module. :ref:`trade.ImageData1D` in the :ref:`trade` module.
.. py:function:: magnum.ImageView2D.__init__(self, arg0: magnum.ImageView2D) .. py:function:: magnum.ImageView2D.__init__(self, arg0: magnum.ImageView2D)
:raise RuntimeError: If `trade.ImageData2D.is_compressed` is :py:`True` :raise RuntimeError: If :ref:`trade.ImageData2D.is_compressed` is :py:`True`
This function is used to implement implicit conversion from This function is used to implement implicit conversion from
`trade.ImageData2D` in the `trade` module. :ref:`trade.ImageData2D` in the :ref:`trade` module.
.. py:function:: magnum.ImageView3D.__init__(self, arg0: magnum.ImageView3D) .. py:function:: magnum.ImageView3D.__init__(self, arg0: magnum.ImageView3D)
:raise RuntimeError: If `trade.ImageData3D.is_compressed` is :py:`True` :raise RuntimeError: If :ref:`trade.ImageData3D.is_compressed` is :py:`True`
This function is used to implement implicit conversion from This function is used to implement implicit conversion from
`trade.ImageData3D` in the `trade` module. :ref:`trade.ImageData3D` in the :ref:`trade` module.
.. py:function:: magnum.MutableImageView1D.__init__(self, arg0: magnum.MutableImageView1D) .. py:function:: magnum.MutableImageView1D.__init__(self, arg0: magnum.MutableImageView1D)
:raise RuntimeError: If `trade.ImageData1D.is_compressed` is :py:`True` :raise RuntimeError: If :ref:`trade.ImageData1D.is_compressed` is :py:`True`
This function is used to implement implicit conversion from This function is used to implement implicit conversion from
`trade.ImageData1D` in the `trade` module. :ref:`trade.ImageData1D` in the :ref:`trade` module.
.. py:function:: magnum.MutableImageView2D.__init__(self, arg0: magnum.MutableImageView2D) .. py:function:: magnum.MutableImageView2D.__init__(self, arg0: magnum.MutableImageView2D)
:raise RuntimeError: If `trade.ImageData2D.is_compressed` is :py:`True` :raise RuntimeError: If :ref:`trade.ImageData2D.is_compressed` is :py:`True`
This function is used to implement implicit conversion from This function is used to implement implicit conversion from
`trade.ImageData2D` in the `trade` module. :ref:`trade.ImageData2D` in the :ref:`trade` module.
.. py:function:: magnum.MutableImageView3D.__init__(self, arg0: magnum.MutableImageView3D) .. py:function:: magnum.MutableImageView3D.__init__(self, arg0: magnum.MutableImageView3D)
:raise RuntimeError: If `trade.ImageData3D.is_compressed` is :py:`True` :raise RuntimeError: If :ref:`trade.ImageData3D.is_compressed` is :py:`True`
This function is used to implement implicit conversion from This function is used to implement implicit conversion from
`trade.ImageData3D` in the `trade` module. :ref:`trade.ImageData3D` in the :ref:`trade` module.

32
doc/python/magnum.shaders.rst
Unescape View File

@ -36,14 +36,18 @@
:data COLOR4: Four-component vertex color :data COLOR4: Four-component vertex color
.. py:property:: magnum.shaders.Flat2D.alpha_mask .. py:property:: magnum.shaders.Flat2D.alpha_mask
:raise AttributeError: If the shader was not created with `Flags.ALPHA_MASK` :raise AttributeError: If the shader was not created with
:ref:`Flags.ALPHA_MASK`
.. py:property:: magnum.shaders.Flat3D.alpha_mask .. py:property:: magnum.shaders.Flat3D.alpha_mask
:raise AttributeError: If the shader was not created with `Flags.ALPHA_MASK` :raise AttributeError: If the shader was not created with
:ref:`Flags.ALPHA_MASK`
.. py:function:: magnum.shaders.Flat2D.bind_texture .. py:function:: magnum.shaders.Flat2D.bind_texture
:raise AttributeError: If the shader was not created with `Flags.TEXTURED` :raise AttributeError: If the shader was not created with
:ref:`Flags.TEXTURED`
.. py:function:: magnum.shaders.Flat3D.bind_texture .. py:function:: magnum.shaders.Flat3D.bind_texture
:raise AttributeError: If the shader was not created with `Flags.TEXTURED` :raise AttributeError: If the shader was not created with
:ref:`Flags.TEXTURED`
.. py:class:: magnum.shaders.VertexColor2D .. py:class:: magnum.shaders.VertexColor2D
:data POSITION: Vertex position :data POSITION: Vertex position
@ -64,25 +68,27 @@
:data COLOR4: Four-component vertex color :data COLOR4: Four-component vertex color
.. py:property:: magnum.shaders.Phong.alpha_mask .. py:property:: magnum.shaders.Phong.alpha_mask
:raise AttributeError: If the shader was not created with `Flags.ALPHA_MASK` :raise AttributeError: If the shader was not created with
:ref:`Flags.ALPHA_MASK`
.. py:property:: magnum.shaders.Phong.light_positions .. py:property:: magnum.shaders.Phong.light_positions
:raise ValueError: If list length is different from `light_count` :raise ValueError: If list length is different from :ref:`light_count`
.. py:property:: magnum.shaders.Phong.light_colors .. py:property:: magnum.shaders.Phong.light_colors
:raise ValueError: If list length is different from `light_count` :raise ValueError: If list length is different from :ref:`light_count`
.. py:function:: magnum.shaders.Phong.bind_ambient_texture .. py:function:: magnum.shaders.Phong.bind_ambient_texture
:raise AttributeError: If the shader was not created with :raise AttributeError: If the shader was not created with
`Flags.AMBIENT_TEXTURE` :ref:`Flags.AMBIENT_TEXTURE`
.. py:function:: magnum.shaders.Phong.bind_diffuse_texture .. py:function:: magnum.shaders.Phong.bind_diffuse_texture
:raise AttributeError: If the shader was not created with :raise AttributeError: If the shader was not created with
`Flags.DIFFUSE_TEXTURE` :ref:`Flags.DIFFUSE_TEXTURE`
.. py:function:: magnum.shaders.Phong.bind_specular_texture .. py:function:: magnum.shaders.Phong.bind_specular_texture
:raise AttributeError: If the shader was not created with :raise AttributeError: If the shader was not created with
`Flags.SPECULAR_TEXTURE` :ref:`Flags.SPECULAR_TEXTURE`
.. py:function:: magnum.shaders.Phong.bind_normal_texture .. py:function:: magnum.shaders.Phong.bind_normal_texture
:raise AttributeError: If the shader was not created with :raise AttributeError: If the shader was not created with
`Flags.NORMAL_TEXTURE` :ref:`Flags.NORMAL_TEXTURE`
.. py:function:: magnum.shaders.Phong.bind_textures .. py:function:: magnum.shaders.Phong.bind_textures
:raise AttributeError: If the shader was not created with any of :raise AttributeError: If the shader was not created with any of
`Flags.AMBIENT_TEXTURE`, `Flags.DIFFUSE_TEXTURE`, :ref:`Flags.AMBIENT_TEXTURE`, :ref:`Flags.DIFFUSE_TEXTURE`,
`Flags.SPECULAR_TEXTURE` or `Flags.NORMAL_TEXTURE` :ref:`Flags.SPECULAR_TEXTURE` or :ref:`Flags.NORMAL_TEXTURE`

80
doc/python/magnum.trade.rst
Unescape View File

@ -25,57 +25,58 @@
.. py:class:: magnum.trade.ImageData1D .. py:class:: magnum.trade.ImageData1D
See `ImageData2D` for more information. See :ref:`ImageData2D` for more information.
.. py:class:: magnum.trade.ImageData2D .. py:class:: magnum.trade.ImageData2D
Similarly to `Image2D`, holds its own data buffer, thus doesn't have an Similarly to :ref:`Image2D`, holds its own data buffer, thus doesn't have
equivalent to `ImageView2D.owner`. Implicitly convertible to `ImageView2D` an equivalent to :ref:`ImageView2D.owner`. Implicitly convertible to
/ `MutableImageView2D`, so all APIs consuming image views work with this :ref:`ImageView2D` / :ref:`MutableImageView2D`, so all APIs consuming image
type as well. views work with this type as well.
.. py:class:: magnum.trade.ImageData3D .. py:class:: magnum.trade.ImageData3D
See `ImageData2D` for more information. See :ref:`ImageData2D` for more information.
.. py:property:: magnum.trade.ImageData1D.storage .. py:property:: magnum.trade.ImageData1D.storage
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData2D.storage .. py:property:: magnum.trade.ImageData2D.storage
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData3D.storage .. py:property:: magnum.trade.ImageData3D.storage
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData1D.format .. py:property:: magnum.trade.ImageData1D.format
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData2D.format .. py:property:: magnum.trade.ImageData2D.format
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData3D.format .. py:property:: magnum.trade.ImageData3D.format
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData1D.pixel_size .. py:property:: magnum.trade.ImageData1D.pixel_size
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData2D.pixel_size .. py:property:: magnum.trade.ImageData2D.pixel_size
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData3D.pixel_size .. py:property:: magnum.trade.ImageData3D.pixel_size
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData1D.pixels .. py:property:: magnum.trade.ImageData1D.pixels
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData2D.pixels .. py:property:: magnum.trade.ImageData2D.pixels
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:property:: magnum.trade.ImageData3D.pixels .. py:property:: magnum.trade.ImageData3D.pixels
:raise AttributeError: If `is_compressed` is :py:`True` :raise AttributeError: If :ref:`is_compressed` is :py:`True`
.. py:class:: magnum.trade.ImporterManager .. py:class:: magnum.trade.ImporterManager
:summary: Manager for `AbstractImporter` plugin instances :summary: Manager for :ref:`AbstractImporter` plugin instances
Each plugin returned by `instantiate()` or `load_and_instantiate()` Each plugin returned by :ref:`instantiate()` or :ref:`load_and_instantiate()`
references its owning `ImporterManager` through `AbstractImporter.manager`, references its owning :ref:`ImporterManager` through
ensuring the manager is not deleted before the plugin instances are. :ref:`AbstractImporter.manager`, ensuring the manager is not deleted before
the plugin instances are.
.. py:class:: magnum.trade.AbstractImporter .. py:class:: magnum.trade.AbstractImporter
Similarly to C++, importer plugins are loaded through `ImporterManager`: Similarly to C++, importer plugins are loaded through :ref:`ImporterManager`:
.. ..
>>> from magnum import trade >>> from magnum import trade
@ -99,15 +100,15 @@
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
.. py:function:: magnum.trade.AbstractImporter.mesh_level_count .. py:function:: magnum.trade.AbstractImporter.mesh_level_count
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `mesh_count` :raise ValueError: If :p:`id` is negative or not less than :ref:`mesh_count`
.. py:function:: magnum.trade.AbstractImporter.mesh_for_name .. py:function:: magnum.trade.AbstractImporter.mesh_for_name
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
.. py:function:: magnum.trade.AbstractImporter.mesh_name .. py:function:: magnum.trade.AbstractImporter.mesh_name
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `mesh_count` :raise ValueError: If :p:`id` is negative or not less than :ref:`mesh_count`
.. py:function:: magnum.trade.AbstractImporter.mesh .. py:function:: magnum.trade.AbstractImporter.mesh
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `mesh_count` :raise ValueError: If :p:`id` is negative or not less than :ref:`mesh_count`
.. py:property:: magnum.trade.AbstractImporter.image1d_count .. py:property:: magnum.trade.AbstractImporter.image1d_count
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
@ -118,13 +119,16 @@
.. py:function:: magnum.trade.AbstractImporter.image1d_level_count .. py:function:: magnum.trade.AbstractImporter.image1d_level_count
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image1d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image1d_count`
.. py:function:: magnum.trade.AbstractImporter.image2d_level_count .. py:function:: magnum.trade.AbstractImporter.image2d_level_count
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image2d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image2d_count`
.. py:function:: magnum.trade.AbstractImporter.image3d_level_count .. py:function:: magnum.trade.AbstractImporter.image3d_level_count
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image3d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image3d_count`
.. py:function:: magnum.trade.AbstractImporter.image1d_for_name .. py:function:: magnum.trade.AbstractImporter.image1d_for_name
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
@ -135,20 +139,26 @@
.. py:function:: magnum.trade.AbstractImporter.image1d_name .. py:function:: magnum.trade.AbstractImporter.image1d_name
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image1d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image1d_count`
.. py:function:: magnum.trade.AbstractImporter.image2d_name .. py:function:: magnum.trade.AbstractImporter.image2d_name
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image2d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image2d_count`
.. py:function:: magnum.trade.AbstractImporter.image3d_name .. py:function:: magnum.trade.AbstractImporter.image3d_name
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image3d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image3d_count`
.. py:function:: magnum.trade.AbstractImporter.image1d .. py:function:: magnum.trade.AbstractImporter.image1d
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image1d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image1d_count`
.. py:function:: magnum.trade.AbstractImporter.image2d .. py:function:: magnum.trade.AbstractImporter.image2d
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image2d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image2d_count`
.. py:function:: magnum.trade.AbstractImporter.image3d .. py:function:: magnum.trade.AbstractImporter.image3d
:raise RuntimeError: If no file is opened :raise RuntimeError: If no file is opened
:raise ValueError: If :p:`id` is negative or not less than `image3d_count` :raise ValueError: If :p:`id` is negative or not less than
:ref:`image3d_count`

51
doc/python/pages/api-conventions.rst
Unescape View File

@ -52,12 +52,12 @@ useful in a Python setting.
.. class:: m-table .. class:: m-table
=================================== ============================ =================================== ==================================
C++ Python C++ Python
=================================== ============================ =================================== ==================================
:dox:`CORRADE_BUILD_MULTITHREADED` `corrade.BUILD_MULTITHREADED` :dox:`CORRADE_BUILD_MULTITHREADED` :ref:`corrade.BUILD_MULTITHREADED`
:dox:`MAGNUM_TARGET_GLES` `magnum.TARGET_GLES` :dox:`MAGNUM_TARGET_GLES` :ref:`magnum.TARGET_GLES`
=================================== ============================ =================================== ==================================
`Namespaces / modules`_ `Namespaces / modules`_
----------------------- -----------------------
@ -67,8 +67,8 @@ C++ Python
=================================== ============================ =================================== ============================
C++ Python C++ Python
=================================== ============================ =================================== ============================
:dox:`Magnum::Math` `magnum.math` :dox:`Magnum::Math` :ref:`magnum.math`
:dox:`Magnum::SceneGraph` `magnum.scenegraph` :dox:`Magnum::SceneGraph` :ref:`magnum.scenegraph`
=================================== ============================ =================================== ============================
`Classes`_ `Classes`_
@ -79,8 +79,8 @@ C++ Python
=================================== ============================ =================================== ============================
C++ Python C++ Python
=================================== ============================ =================================== ============================
:dox:`Vector2i` `Vector2i` :dox:`Vector2i` :ref:`Vector2i`
:dox:`GL::Buffer` `gl.Buffer` :dox:`GL::Buffer` :ref:`gl.Buffer`
=================================== ============================ =================================== ============================
`Functions`_ `Functions`_
@ -91,10 +91,10 @@ C++ Python
=============================================================== =========== =============================================================== ===========
C++ Python C++ Python
=============================================================== =========== =============================================================== ===========
:dox:`Math::angle()` `math.angle()` :dox:`Math::angle()` :ref:`math.angle()`
:dox:`Vector2::xAxis() <Math::Vector2::xAxis()>` `Vector2.x_axis()` :dox:`Vector2::xAxis() <Math::Vector2::xAxis()>` :ref:`Vector2.x_axis()`
:dox:`v.isZero() <Math::Vector::isZero()>` `v.is_zero() <Vector3.is_zero()>` :dox:`v.isZero() <Math::Vector::isZero()>` :ref:`v.is_zero() <Vector3.is_zero()>`
:dox:`m.transformVector(a) <Math::Matrix4::transformVector()>` `m.transform_vector(a) <Matrix4.transform_vector()>` :dox:`m.transformVector(a) <Math::Matrix4::transformVector()>` :ref:`m.transform_vector(a) <Matrix4.transform_vector()>`
=============================================================== =========== =============================================================== ===========
`Enums`_ `Enums`_
@ -105,24 +105,24 @@ C++ Python
============================================== ============================ ============================================== ============================
C++ Python C++ Python
============================================== ============================ ============================================== ============================
:dox:`PixelFormat::RGB8Unorm` `PixelFormat.RGB8_UNORM` :dox:`PixelFormat::RGB8Unorm` :ref:`PixelFormat.RGB8_UNORM`
:dox:`MeshPrimitive::TriangleStrip` `MeshPrimitive.TRIANGLE_STRIP` :dox:`MeshPrimitive::TriangleStrip` :ref:`MeshPrimitive.TRIANGLE_STRIP`
============================================== ============================ ============================================== ============================
`Constants`_ `Constants`_
------------ ------------
Apart from :dox:`Math::Constants`, which are exposed directly as members of the Apart from :dox:`Math::Constants`, which are exposed directly as members of the
`magnum.math` submodule to mimic Python's `math`, most of the constants used :ref:`magnum.math` submodule to mimic Python's :ref:`math`, most of the
throughout the C++ API are related to templates. Those are, where applicable, constants used throughout the C++ API are related to templates. Those are,
converted to Python builtins such as :py:`len()`. where applicable, converted to Python builtins such as :py:`len()`.
.. class:: m-table .. class:: m-table
============================================== ============================ ============================================== ============================
C++ Python C++ Python
============================================== ============================ ============================================== ============================
:dox:`Constants::pi() <Math::Constants::pi()>` `math.pi <magnum.math.pi>` :dox:`Constants::pi() <Math::Constants::pi()>` :ref:`math.pi <magnum.math.pi>`
:dox:`Math::Vector::Size` :py:`len(vec)` :dox:`Math::Vector::Size` :py:`len(vec)`
============================================== ============================ ============================================== ============================
@ -189,14 +189,14 @@ In particular, both the C++ and the Python API is designed in a way to prevent
too generic or confusing names in the root namespace / module and also keeping too generic or confusing names in the root namespace / module and also keeping
it relatively clean and small, without too many symbols. On the other hand, the it relatively clean and small, without too many symbols. On the other hand, the
subnamespaces *do* have generic names. The :dox:`GL::version()` / subnamespaces *do* have generic names. The :dox:`GL::version()` /
`gl.version()` API is one example --- it's tucked in a subnamespace so the :ref:`gl.version()` API is one example --- it's tucked in a subnamespace so the
generic name isn't a problem, but you wouldn't find anything of similar generic name isn't a problem, but you wouldn't find anything of similar
genericity in the root namespace / module. genericity in the root namespace / module.
An exception to this rule is exposed preprocessor definitions --- these are An exception to this rule is exposed preprocessor definitions --- these are
*not* pulled in when doing :py:`from magnum import *` as this would likely *not* pulled in when doing :py:`from magnum import *` as this would likely
cause conflicts (in particular, `BUILD_STATIC` is defined by Corrade as well). cause conflicts (in particular, :ref:`BUILD_STATIC` is defined by Corrade as
Instead, you have to access them like this: well). Instead, you have to access them like this:
.. code:: py .. code:: py
@ -224,9 +224,10 @@ C++ APIs that have alternative implementations (such as
typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D; typedef SceneGraph::Object<SceneGraph::MatrixTransformation3D> Object3D;
In Python, the alternate implementations are tucked in submodules (such as In Python, the alternate implementations are tucked in submodules (such as
`platform.sdl2` vs. `platform.glfw`, or `scenegraph.matrix` vs. :ref:`platform.sdl2` vs. :ref:`platform.glfw`, or :ref:`scenegraph.matrix` vs.
`scenegraph.trs`), each submodule providing the same names (such as :ref:`scenegraph.trs`), each submodule providing the same names (such as
`Application <platform.sdl2.Application>` or `Object3D <scenegraph.matrix.Object3D>`) :ref:`Application <platform.sdl2.Application>` or
:ref:`Object3D <scenegraph.matrix.Object3D>`)
and the designed way to use them is via :py:`from ... import`: and the designed way to use them is via :py:`from ... import`:
.. code:: py .. code:: py

6
doc/python/pages/building.rst
Unescape View File

@ -157,9 +157,9 @@ running them is then a matter of:
.. block-default:: Disabling GL tests .. block-default:: Disabling GL tests
If the tests detect that one of If the tests detect that one of
`platform.WindowlessApplication <platform.egl.WindowlessApplication>`\ s is :ref:`platform.WindowlessApplication <platform.egl.WindowlessApplication>`\ s
present, GL tests (suffixed with ``_gl``) will be run as well. In order to is present, GL tests (suffixed with ``_gl``) will be run as well. In order
disable them (for example when running on a headless CI), set the to disable them (for example when running on a headless CI), set the
:sh:`$MAGNUM_SKIP_GL_TESTS` environment variable to ``ON``: :sh:`$MAGNUM_SKIP_GL_TESTS` environment variable to ``ON``:
.. code:: sh .. code:: sh

27
doc/python/pages/changelog.rst
Unescape View File

@ -38,20 +38,21 @@ Changelog
Released 2020-06-27, tagged as Released 2020-06-27, tagged as
:gh:`v2020.06 <mosra/magnum-bindings/releases/tag/v2020.06>`. :gh:`v2020.06 <mosra/magnum-bindings/releases/tag/v2020.06>`.
- Exposed `Matrix4.cofactor()`, `Matrix4.comatrix()`, `Matrix4.adjugate()` - Exposed :ref:`Matrix4.cofactor()`, :ref:`Matrix4.comatrix()`,
(and equivalents in other matrix sizes), and `Matrix4.normal_matrix()` :ref:`Matrix4.adjugate()` (and equivalents in other matrix sizes), and
- Exposed `gl.AbstractFramebuffer.blit()` functions and related enums :ref:`Matrix4.normal_matrix()`
- Exposed more keys in `platform.sdl2.Application` and - Exposed :ref:`gl.AbstractFramebuffer.blit()` functions and related enums
`platform.glfw.Application` - Exposed more keys in :ref:`platform.sdl2.Application` and
- Exposed `gl.AbstractTexture.unbind()` :ref:`platform.glfw.Application`
- Exposed `trade.AbstractImporter.image2d_level_count()` and related APIs for - Exposed :ref:`gl.AbstractTexture.unbind()`
1D and 3D - Exposed :ref:`trade.AbstractImporter.image2d_level_count()` and related
- Exposed `trade.MeshData` and related APIs, the previous APIs for 1D and 3D
- Exposed :ref:`trade.MeshData` and related APIs, the previous
``trade.MeshData3D`` APIs are removed ``trade.MeshData3D`` APIs are removed
- Exposed new APIs and tangent support in the `primitives` library - Exposed new APIs and tangent support in the :ref:`primitives` library
- `platform.sdl2.Application` and `platform.glfw.Application` now provide a - :ref:`platform.sdl2.Application` and :ref:`platform.glfw.Application` now
clear error instead of "pure virtual method call" in case ``draw_event()`` provide a clear error instead of "pure virtual method call" in case
is not implemented ``draw_event()`` is not implemented
- Library version is now exposed through ``MAGNUMBINDINGS_VERSION_YEAR``, - Library version is now exposed through ``MAGNUMBINDINGS_VERSION_YEAR``,
``MAGNUMBINDINGS_VERSION_MONTH``, ``MAGNUMBINDINGS_VERSION_COMMIT``, ``MAGNUMBINDINGS_VERSION_MONTH``, ``MAGNUMBINDINGS_VERSION_COMMIT``,
``MAGNUMBINDINGS_VERSION_HASH`` and ``MAGNUMBINDINGS_VERSION_STRING`` ``MAGNUMBINDINGS_VERSION_HASH`` and ``MAGNUMBINDINGS_VERSION_STRING``

10
doc/python/pages/index.rst
Unescape View File

@ -42,11 +42,11 @@ the C++ docs --- highlighting important differences and describing general
conventions, but referring to documentation of underlying C++ APIs for all conventions, but referring to documentation of underlying C++ APIs for all
details. details.
See the `building docs <std:doc:building>` for an installation guide, See the :ref:`building docs <std:doc:building>` for an installation guide,
`API convention documentation <std:doc:api-conventions>` and :ref:`API convention documentation <std:doc:api-conventions>` and
`documentation of each module <std:special:modules>` for more information about :ref:`documentation of each module <std:special:modules>` for more information about
the actual usage. There are also `examples <std:doc:examples>` to give you an the actual usage. There are also :ref:`examples <std:doc:examples>` to give you
idea about how the API feels. an idea about how the API feels.
`Contact & support`_ `Contact & support`_
==================== ====================

Write Preview
Loading…
Cancel
Save