wolfhece.opengl.wolf_array_shader2d
===================================

.. py:module:: wolfhece.opengl.wolf_array_shader2d

.. autoapi-nested-parse::

   Shared-resource 2D shader rendering for WolfArray.

   Instead of creating a separate WolfArrayPlotShader per grid cell
   (each with its own shader program, z-texture upload, palette upload),
   we compile the shader program ONCE, upload the z-texture and palette
   ONCE, concatenate all visible quad-centers into a SINGLE VBO, and
   issue a SINGLE glDrawArrays call.

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

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







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

.. py:data:: SHADER_DIR

.. py:data:: _DTYPE_GL_MAP

.. py:class:: WolfArrayShader2D(owner)

   Manages shared OpenGL resources for 2D shader rendering of a WolfArray.

   Holds a back-reference to the owning WolfArray to access grid data,
   palette, mapviewer, and LOD helpers.


   .. py:attribute:: _owner


   .. py:attribute:: _program
      :value: None



   .. py:attribute:: _locs
      :value: None



   .. py:attribute:: _ztexture_id
      :value: None



   .. py:attribute:: _palette_id
      :value: None



   .. py:attribute:: _vao
      :value: None



   .. py:attribute:: _vbo
      :value: None



   .. py:attribute:: _merged_count
      :value: 0



   .. py:attribute:: _visible_key
      :value: None



   .. py:attribute:: _quad_cache


   .. py:attribute:: _color_values_buf


   .. py:attribute:: _pal_values
      :value: None



   .. py:attribute:: _pal_size
      :value: 0



   .. py:attribute:: _ztext_ready
      :value: False



   .. py:attribute:: _pal_ready
      :value: False



   .. py:attribute:: _dtype_define
      :value: None



   .. py:attribute:: _tile_textures


   .. py:attribute:: _tile_size
      :value: None



   .. py:attribute:: _n_tiles
      :value: (1, 1)



   .. py:attribute:: _tiled
      :value: False



   .. py:attribute:: _tile_ranges


   .. py:attribute:: _tile_visible_key
      :value: None



   .. py:method:: _init_resources(dtype_define=None)

      Compile the shared shader program and locate uniforms.

      :param dtype_define: Optional preprocessor define to inject into the
          geometry shader ('SIGNED_INTEGER_DATA' or 'UNSIGNED_INTEGER_DATA').
          When *None* the shader uses ``sampler2DRect`` (float textures).



   .. py:method:: _ensure_ztexture()

      Upload the z-texture to the GPU.

      If the array fits within ``GL_MAX_RECTANGLE_TEXTURE_SIZE`` in
      both dimensions, a single rectangle texture is created (fast
      path).  Otherwise the data is split into a grid of tile
      textures, each within the hardware limit.



   .. py:method:: _ensure_palette()

      Upload the palette 1-D texture to the GPU.



   .. py:method:: cleanup()

      Release all shared GL resources.



   .. py:method:: _ensure_vao_vbo()

      Create the shared VAO/VBO pair (once).



   .. py:method:: _upload_vbo(data)

      Upload float32 vertex data to the shared VBO.



   .. py:method:: _set_common_uniforms(wa, lod)

      Set uniforms shared between tiled and non-tiled draw paths.



   .. py:method:: _build_tile_vbo_data(wa, lod, istart, iend, jstart, jend)

      Group visible quad centers by texture tile and merge into one VBO.

      :return: ``(merged_vbo, tile_ranges)`` where *merged_vbo* is a
          concatenated ``np.float32`` array and *tile_ranges* maps
          ``(tx, ty)`` to ``(vbo_offset, vertex_count)`` for
          ``glDrawArrays``.



   .. py:method:: draw(sx: float = None, sy: float = None, xmin: float = None, ymin: float = None, xmax: float = None, ymax: float = None)

      Draw using a single shared shader program.

      When the array fits in a single texture, issues a single
      ``glDrawArrays`` call.  When tiled (array exceeds max texture
      size), iterates over visible tiles, binding each tile's texture
      and setting per-tile offset uniforms.