wolfhece.opengl.polyline_shader2d
=================================

.. py:module:: wolfhece.opengl.polyline_shader2d

.. autoapi-nested-parse::

   Shared-resource polyline shader for vector rendering.

   Renders polylines as geometry-shader-extruded quads with support for:
   - Variable width along the polyline
   - Dash / dot patterns
   - Glow effect
   - Animation (pulse, marching ants)

   The shader program is compiled ONCE and reused for all vectors.

   Author: HECE - University of Liege, Pierre Archambeau
   Date: 2026

   Copyright (c) 2026 University of Liege. All rights reserved.









Module Contents
---------------

.. py:data:: SHADER_DIR

.. py:data:: _STRIDE
   :value: 4


.. py:data:: _BYTES_PER_FLOAT
   :value: 4


.. py:class:: PolylineShader2D

   Shared-resource polyline shader with VBO management.

   A single instance is shared across all vector/zone rendering.
   Call :meth:`draw_polyline` for each polyline to render.


   .. py:attribute:: _instance
      :type:  PolylineShader2D | None
      :value: None



   .. py:attribute:: _program
      :type:  int | None
      :value: None



   .. py:attribute:: _locs
      :type:  dict | None
      :value: None



   .. py:attribute:: _vao
      :type:  int | None
      :value: None



   .. py:attribute:: _vbo
      :type:  int | None
      :value: None



   .. py:attribute:: _draw_count
      :type:  int
      :value: 0



   .. py:method:: get_instance() -> PolylineShader2D
      :classmethod:


      Return the singleton instance, creating it if needed.



   .. py:method:: _init_program()

      Compile and link vertex / geometry / fragment shaders.



   .. py:method:: _compile_shader(shader_type: int, path: pathlib.Path) -> int
      :staticmethod:


      Compile a single GLSL shader from *path*.



   .. py:method:: _ensure_vao_vbo()

      Create the shared VAO/VBO pair (once).



   .. py:method:: _upload(data: numpy.ndarray)

      Upload float32 vertex data to the shared VBO.



   .. py:method:: destroy()

      Release all GPU resources.



   .. py:method:: draw_polyline(vbo_data: numpy.ndarray, vertex_count: int, mvp: numpy.ndarray, viewport: tuple[int, int], color: tuple[float, float, float, float], line_width: float = 2.0, width_in_pixels: bool = True, aa_radius: float = 0.06, dash_enabled: bool = False, dash_length: float = 10.0, gap_length: float = 5.0, dash_offset: float = 0.0, glow_enabled: bool = False, glow_width: float = 0.4, glow_color: tuple[float, float, float, float] = (1.0, 1.0, 1.0, 0.4), anim_phase: float = 0.0, anim_mode: int = 0, join_style: int = 0, join_size: float = 1.0)

      Draw a single polyline with the shader pipeline.

      :param vbo_data: float32 array of shape ``(N, 4)`` — ``[x, y, dist, width]`` per vertex.
      :param vertex_count: Number of vertices in *vbo_data*.
      :param mvp: 4×4 projection matrix (column-major float32).
      :param viewport: ``(width_px, height_px)`` of the viewport.
      :param color: ``(r, g, b, a)`` each in ``[0, 1]``.
      :param line_width: Full visible width of the line (pixels or world units), same semantics as ``glLineWidth``.
      :param width_in_pixels: If ``True``, *line_width* is in pixels.
      :param aa_radius: Anti-aliasing smoothing (0–1 in edge space).
      :param dash_enabled: Enable the dash pattern.
      :param dash_length: Dash length in world units.
      :param gap_length: Gap length in world units.
      :param dash_offset: Pattern offset for animation.
      :param glow_enabled: Enable the glow halo.
      :param glow_width: Glow halo extent as fraction of core half-width (e.g. 0.4 adds 40% extra width on each side).
      :param glow_color: ``(r, g, b, a)`` for the glow.
      :param anim_phase: Animation phase ``[0, 1]``.
      :param anim_mode: ``0`` = none, ``1`` = pulse alpha, ``2`` = marching ants.
      :param join_style: ``0`` = miter, ``1`` = bevel, ``2`` = round.
      :param join_size: Join radius multiplier (``1.0`` = line half-width).



.. py:function:: build_polyline_vbo(vertices: list, widths: numpy.ndarray | None = None) -> tuple[numpy.ndarray, int]

   Build VBO data for a polyline from a list of wolfvertex objects.

   Each segment is emitted as four vertices for ``GL_LINES_ADJACENCY``
   (prev, start, end, next) to be consumed by the geometry shader
   for miter join computation.

   :param vertices: List of objects with ``.x`` and ``.y`` attributes.
   :param widths: Optional per-vertex width multipliers (length `N`).
                  Defaults to ``1.0`` for all vertices.
   :returns: ``(vbo_data, vertex_count)`` where *vbo_data* is a contiguous
             float32 array of shape ``(vertex_count, 4)`` and *vertex_count*
             is the number of vertices (= 4 × number of segments).