render
Module#
Classes#
- class term_image.render.RenderIterator(renderable, render_args=None, padding=ExactPadding(left=0, top=0, right=0, bottom=0, fill=' '), loops=1, cache=100)[source]#
Bases:
object
An iterator for efficient iteration over rendered frames of an animated renderable.
- Parameters:
renderable (Renderable) – An animated renderable.
render_args (RenderArgs | None) – Render arguments.
padding (Padding) – Render output padding.
loops (int) –
The number of times to go over all frames.
< 0
-> loop infinitely.0
-> invalid.> 0
-> loop the given number of times.
Note
The value is ignored and taken to be
1
(one), if renderable hasINDEFINITE
frame count.Determines if rendered frames are cached.
If the value is
True
or a positive integer greater than or equal to the frame count of renderable, caching is enabled. Otherwise i.eFalse
or a positive integer less than the frame count, caching is disabled.Note
The value is ignored and taken to be
False
, if renderable hasINDEFINITE
frame count.
- Raises:
ValueError – An argument has an invalid value.
IncompatibleRenderArgsError – Incompatible render arguments.
The iterator yields a
Frame
instance on every iteration.Note
Seeking the underlying renderable (via
Renderable.seek()
) does not affect an iterator, useRenderIterator.seek()
instead. Likewise, the iterator does not modify the underlying renderable’s current frame number.Changes to the underlying renderable’s render size does not affect an iterator’s render outputs, use
set_render_size()
instead.Changes to the underlying renderable’s
frame_duration
does not affect the value yiedled by an iterator, the value when initializing the iterator is what it will use.
See also
Renderable.__iter__()
Renderables are iterable
- RenderIterator
RenderIterator
‘s Extension API
Attributes:
Iteration loop countdown
Instance Methods:
Finalizes the iterator and releases resources used.
Sets the frame to be rendered on the next iteration, without affecting the loop count.
Sets the frame duration.
Sets the render output padding.
Sets the render arguments.
Sets the render size.
- loop: int#
Iteration loop countdown
A negative integer, if iteration is infinite.
Otherwise, the current iteration loop countdown value.
Starts from the value of the loops constructor argument,
decreases by one upon rendering the first frame of every loop after the first,
and ends at zero after the iterator is exhausted.
Note
Modifying this doesn’t affect the iterator.
- close()[source]#
Finalizes the iterator and releases resources used.
Note
This method is automatically called when the iterator is exhausted or garbage-collected but it’s recommended to call it manually if iteration is ended prematurely (i.e before the iterator itself is exhausted), especially if frames are cached.
This method is safe for multiple invocations.
- seek(offset, whence=Seek.START)[source]#
Sets the frame to be rendered on the next iteration, without affecting the loop count.
- Parameters:
- Raises:
FinalizedIteratorError – The iterator has been finalized.
ValueError – offset is out of range.
The value range for offset depends on the
frame_count
of the underlying renderable and whence:# whence
Valid value range for offset
0
<= offset <frame_count
-next_frame_number [1] <= offset <
frame_count
- next_frame_number-
frame_count
< offset <=0
Note
If the underlying renderable has definite frame count, seek operations have immeditate effect. Hence, multiple consecutive seek operations, starting with any kind and followed by one or more with whence =
CURRENT
, between any two consecutive renders have a cumulative effect. In particular, any seek operation with whence =CURRENT
is relative to the frame to be rendered next [1].Example
>>> animated_renderable.frame_count 10 >>> render_iter = RenderIterator(animated_renderable) # next = 0 >>> render_iter.seek(5) # next = 5 >>> next(render_iter).number # next = 5 + 1 = 6 5 >>> # cumulative >>> render_iter.seek(2, Seek.CURRENT) # next = 6 + 2 = 8 >>> render_iter.seek(-4, Seek.CURRENT) # next = 8 - 4 = 4 >>> next(render_iter).number # next = 4 + 1 = 5 4 >>> # cumulative >>> render_iter.seek(7) # next = 7 >>> render_iter.seek(1, Seek.CURRENT) # next = 7 + 1 = 8 >>> render_iter.seek(-5, Seek.CURRENT) # next = 8 - 5 = 3 >>> next(render_iter).number # next = 3 + 1 = 4 3 >>> # NOT cumulative >>> render_iter.seek(3, Seek.CURRENT) # next = 4 + 3 = 7 >>> render_iter.seek(2) # next = 2 >>> next(render_iter).number # next = 2 + 1 = 3 2
On the other hand, if the underlying renderable has
INDEFINITE
frame count, seek operations don’t take effect until the next render. Hence, multiple consecutive seek operations between any two consecutive renders do not have a cumulative effect; rather, only the last one takes effect. In particular, any seek operation with whence =CURRENT
is relative to the frame after that which was rendered last.Example
>>> animated_renderable.frame_count is FrameCount.INDEFINITE True >>> # iterating normally without seeking >>> [frame.render_output for frame in animated_renderable] ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', 'A', ...] >>> >>> # Assuming the renderable implements all kinds of seek operations >>> render_iter = RenderIterator(animated_renderable) # next = 0 >>> render_iter.seek(5) # next = 5 >>> next(render_iter).render_output # next = 5 + 1 = 6 '5' >>> render_iter.seek(2, Seek.CURRENT) # next = 6 + 2 = 8 >>> render_iter.seek(-4, Seek.CURRENT) # next = 6 - 4 = 2 >>> next(render_iter).render_output # next = 2 + 1 = 3 '2' >>> render_iter.seek(7) # next = 7 >>> render_iter.seek(3, Seek.CURRENT) # next = 3 + 3 = 6 >>> next(render_iter).render_output # next = 6 + 1 = 7 '6'
A renderable with
INDEFINITE
frame count may not support/implement all kinds of seek operations or any at all. If the underlying renderable doesn’t support/implement a given seek operation, the seek operation should simply have no effect on iteration i.e the next frame should be the one after that which was rendered last. See each render class that implementsINDEFINITE
frame count for the seek operations it supports and any other specific related details.
- set_frame_duration(duration)[source]#
Sets the frame duration.
- Parameters:
duration (int | FrameDuration) – Frame duration (see
frame_duration
).- Raises:
FinalizedIteratorError – The iterator has been finalized.
ValueError – duration is out of range.
Note
Takes effect from the next [1] rendered frame.
- set_padding(padding)[source]#
Sets the render output padding.
- Parameters:
padding (Padding) – Render output padding.
- Raises:
FinalizedIteratorError – The iterator has been finalized.
Note
Takes effect from the next [1] rendered frame.
- set_render_args(render_args)[source]#
Sets the render arguments.
- Parameters:
render_args (RenderArgs) – Render arguments.
- Raises:
FinalizedIteratorError – The iterator has been finalized.
IncompatibleRenderArgsError – Incompatible render arguments.
Note
Takes effect from the next [1] rendered frame.
- set_render_size(render_size)[source]#
Sets the render size.
- Parameters:
render_size (Size) – Render size.
- Raises:
FinalizedIteratorError – The iterator has been finalized.
Note
Takes effect from the next [1] rendered frame.
Exceptions#
Base exception class for errors specific to |
|
Raised if certain operations are attempted on a finalized iterator. |
- exception term_image.render.RenderIteratorError[source]#
Bases:
TermImageError
Base exception class for errors specific to
RenderIterator
.
- exception term_image.render.FinalizedIteratorError[source]#
Bases:
RenderIteratorError
Raised if certain operations are attempted on a finalized iterator.
Extension API#
Note
The following definitions are provided and required only for extended use of the interfaces defined above.
Everything required for normal usage should typically be exposed in the public API.
RenderIterator#
- class term_image.render.RenderIterator[source]
See
RenderIterator
for the public API.Class Methods:
Constructs an iterator with pre-generated render data.
- classmethod _from_render_data_(renderable, render_data, render_args=None, padding=ExactPadding(left=0, top=0, right=0, bottom=0, fill=' '), *args, finalize=True, **kwargs)[source]#
Constructs an iterator with pre-generated render data.
- Parameters:
renderable (Renderable) – An animated renderable.
render_data (RenderData) – Render data.
render_args (RenderArgs | None) – Render arguments.
args (Any) – Other positional arguments accepted by the class constructor.
finalize (bool) – Whether render_data is finalized along with the iterator.
kwargs (Any) – Other keyword arguments accepted by the class constructor.
- Returns:
A new iterator instance.
- Return type:
Raises the same exceptions as the class constructor.
Note
render_data may be modified by the iterator or the underlying renderable.
Footnotes