Blender V5.3
bmesh_uvselect.hh File Reference
#include "bmesh_class.hh"
#include "BLI_vector_list.hh"

Go to the source code of this file.

Classes

struct  blender::BMUVSelectPickParams
struct  blender::UVSelectValidateInfo_Sync
struct  blender::UVSelectValidateInfo_Flush
struct  blender::UVSelectValidateInfo_Contiguous
struct  blender::UVSelectValidateInfo_FlushAndContiguous
struct  blender::UVSelectValidateInfo

Namespaces

namespace  blender
 BMesh Iterators.

Functions

UV Selection Functions (low level)

Selection checking functions. These should be used instead of checking BM_ELEM_SELECT_UV, so hidden geometry is never considered selected.

bool blender::BM_face_uvselect_test (const BMFace *f)
bool blender::BM_loop_vert_uvselect_test (const BMLoop *l)
bool blender::BM_loop_edge_uvselect_test (const BMLoop *l)
UV Selection Connectivity Checks

Regarding the hflag parameter: this is typically set to:

Each function asserts that a supported hflag is passed in.

bool blender::BM_loop_vert_uvselect_check_other_loop_vert (BMLoop *l, const char hflag, const int cd_loop_uv_offset)
bool blender::BM_loop_vert_uvselect_check_other_loop_edge (BMLoop *l, const char hflag, const int cd_loop_uv_offset)
bool blender::BM_loop_vert_uvselect_check_other_edge (BMLoop *l, const char hflag, const int cd_loop_uv_offset)
bool blender::BM_loop_vert_uvselect_check_other_face (BMLoop *l, const char hflag, const int cd_loop_uv_offset)
bool blender::BM_loop_edge_uvselect_check_other_loop_edge (BMLoop *l, const char hflag, const int cd_loop_uv_offset)
bool blender::BM_loop_edge_uvselect_check_other_face (BMLoop *l, const char hflag, const int cd_loop_uv_offset)
bool blender::BM_face_uvselect_check_edges_all (BMFace *f)
UV Selection Functions
void blender::BM_face_uvselect_set_noflush (BMesh *bm, BMFace *f, bool select)
void blender::BM_face_uvselect_set (BMesh *bm, BMFace *f, bool select)
void blender::BM_loop_edge_uvselect_set_noflush (BMesh *bm, BMLoop *l, bool select)
void blender::BM_loop_edge_uvselect_set (BMesh *bm, BMLoop *l, bool select)
void blender::BM_loop_vert_uvselect_set_noflush (BMesh *bm, BMLoop *l, bool select)
bool blender::BM_mesh_uvselect_clear (BMesh *bm)
UV Selection Functions (Shared)
void blender::BM_loop_vert_uvselect_set_shared (BMesh *bm, BMLoop *l, bool select, const int cd_loop_uv_offset)
void blender::BM_loop_edge_uvselect_set_shared (BMesh *bm, BMLoop *l, bool select, const int cd_loop_uv_offset)
void blender::BM_face_uvselect_set_shared (BMesh *bm, BMFace *f, bool select, const int cd_loop_uv_offset)
void blender::BM_mesh_uvselect_set_elem_shared (BMesh *bm, bool select, int cd_loop_uv_offset, Span< BMLoop * > loop_verts, Span< BMLoop * > loop_edges, Span< BMFace * > faces)
UV Selection Picking Versions of Selection Functions

These functions differ in that they perform all necessary flushing but do so only on local elements. This is only practical with a small number of elements since it'd be inefficient on large selections.

Note that we could also support selecting face-corners from the 3D viewport using these functions, however that's not yet supported.

Selection Modes & Flushing

Picking an edge in face-select mode or a vertex in edge-select mode is not supported. This is logical because the user cannot select a single vertex in face select mode. As these functions are exposed publicly for picking, this makes some sense.

Internally however, these functions are currently used by BM_mesh_uvselect_set_elem_from_mesh, which corrects "isolated" elements which should not be selected based on the selection-mode.

void blender::BM_vert_uvselect_set_pick (BMesh *bm, BMVert *v, bool select, const BMUVSelectPickParams &params)
void blender::BM_edge_uvselect_set_pick (BMesh *bm, BMEdge *e, bool select, const BMUVSelectPickParams &params)
void blender::BM_face_uvselect_set_pick (BMesh *bm, BMFace *f, bool select, const BMUVSelectPickParams &params)
void blender::BM_mesh_uvselect_set_elem_from_mesh (BMesh *bm, bool select, const BMUVSelectPickParams &params, Span< BMVert * > verts, Span< BMEdge * > edges, Span< BMFace * > faces)
void blender::BM_mesh_uvselect_set_elem_from_mesh (BMesh *bm, bool select, const BMUVSelectPickParams &params, const VectorList< BMVert * > &verts, const VectorList< BMEdge * > &edges, const VectorList< BMFace * > &faces)
UV Selection Flushing (Only Select/De-Select)
Note
In most cases flushing assumes selection has already been flushed down.

This means:

  • A selected edge must have both UV vertices selected.
  • A selected faces has all its edges & vertices selected.

It's often useful to call BM_mesh_uvselect_flush_shared_only_select after using these non-UV-coordinate aware flushing functions.

void blender::BM_mesh_uvselect_flush_from_loop_verts_only_select (BMesh *bm)
void blender::BM_mesh_uvselect_flush_from_loop_verts_only_deselect (BMesh *bm)
void blender::BM_mesh_uvselect_flush_from_loop_edges_only_select (BMesh *bm)
void blender::BM_mesh_uvselect_flush_from_loop_edges_only_deselect (BMesh *bm)
void blender::BM_mesh_uvselect_flush_from_faces_only_select (BMesh *bm)
void blender::BM_mesh_uvselect_flush_from_faces_only_deselect (BMesh *bm)
void blender::BM_mesh_uvselect_flush_shared_only_select (BMesh *bm, const int cd_loop_uv_offset)
void blender::BM_mesh_uvselect_flush_shared_only_deselect (BMesh *bm, const int cd_loop_uv_offset)
UV Selection Flushing (Between Elements)

Regarding the flush_down argument.

Primitive UV selection functions always flush down:

This means it's often only necessary to flush up after the selection has been changed.

void blender::BM_mesh_uvselect_flush_from_loop_verts (BMesh *bm)
void blender::BM_mesh_uvselect_flush_from_loop_edges (BMesh *bm, bool flush_down)
void blender::BM_mesh_uvselect_flush_from_faces (BMesh *bm, bool flush_down)
void blender::BM_mesh_uvselect_flush_from_verts (BMesh *bm, const bool select)
UV Selection Flushing (Selection Mode Aware)
void blender::BM_mesh_uvselect_mode_flush_ex (BMesh *bm, const short selectmode, const bool flush_down)
void blender::BM_mesh_uvselect_mode_flush (BMesh *bm)
void blender::BM_mesh_uvselect_mode_flush_only_select (BMesh *bm)
void blender::BM_mesh_uvselect_mode_flush_update (BMesh *bm, const short selectmode_old, const short selectmode_new, const int cd_loop_uv_offset)
void blender::BM_mesh_uvselect_flush_post_subdivide (BMesh *bm, const int cd_loop_uv_offset)
UV Selection Flushing (From/To Mesh)
void blender::BM_mesh_uvselect_sync_from_mesh_sticky_location (BMesh *bm, const int cd_loop_uv_offset)
void blender::BM_mesh_uvselect_sync_from_mesh_sticky_disabled (BMesh *bm)
void blender::BM_mesh_uvselect_sync_from_mesh_sticky_vert (BMesh *bm)
void blender::BM_mesh_uvselect_sync_to_mesh (BMesh *bm)
UV Selection Validation
bool blender::BM_mesh_uvselect_is_valid (BMesh *bm, const int cd_loop_uv_offset, const bool check_sync, const bool check_flush, const bool check_contiguous, UVSelectValidateInfo *info_p)

Detailed Description

Overview

The BM_uvselect_* API deals with synchronizing selection between UV's and selected vertices edges & faces, where a selected vertex in the 3D viewport may only have some of its UV vertices selected in the UV editor.

Supporting this involves flushing in both directions depending on the selection being edited.

Note
See #78393 for a user-level overview of this functionality. This describes the motivation to synchronize selection between UV's and the mesh.
A short-hand term for vertex/edge/face selection used in this file is View3D abbreviated to v3d, since this is the section manipulated in the viewport, e.g. #BM_mesh_uvselect_sync_to_mesh.
This is quite involved. As a last resort the UV selection can always be cleared and re-set from the mesh (v3d) selection, however it's good to keep UV selection if possible because resetting may extend vertex selection to other UV islands.

Terms

  • Synchronized Selection (abbreviated to "sync"). See #BMesh::uv_select_sync_valid. When the UV synchronized data is valid, it means there is a valid relationship between the UV selection flags (#BM_ELEM_SELECT_UV & BM_ELEM_SELECT_UV_EDGE) and the meshes selection (#BM_ELEM_SELECT_UV).
    • When the UV selection changes (from the UV editor) this needs to be synchronized to the mesh.
    • When the base-selection flags change (from the 3D viewport) this needs to be synchronized to the UV's. Synchronizing in this direction may be lossy, although (depending on the operation), support for maintaining a synchronized selection may be possible.
  • Flushing Selection ("flush") When an element is selected or de-selected, the selection state of connected geometry may change too. So, de-selecting a vertex must de-select all faces that use that vertex.

    The rules for flushing may depend on the selection mode. When de-selecting a face in vertex-select-mode, all its vertices & edges must also be de-selected. When de-selecting a face in face-select-mode, only vertices and edges no longer connected to any selected faces will be de-selected.

    Since applying these rules while selecting individual elements is often impractical, it's common to adjust the selection, then flush based on the selection mode afterwards.

  • Flushing up: Flushing the selection from [verts -> edges/faces], [edges -> faces].
  • Flushing down: Flushing the selection from [faces -> verts/edges], [edges -> verts].
  • Isolated vertex or edge selection: When a vertex or edge is selected without being connected to a selected face.

UV Selection Flags

  • UV selection uses:
    • #BM_ELEM_SELECT_UV & BM_ELEM_SELECT_UV_EDGE for #BMLoop to define selected vertices & edges.
    • #BM_ELEM_SELECT_UV for #BMFace.

Hidden Flags

Unlike viewport selection there is no requirement for hidden elements not to be selected. Therefore, UV selection checks must check the underlying geometry is not hidden. In practice this means hidden faces must be assumed unselected, since UV's are part of the faces (there is no such thing as a hidden face-corner) and any hidden edge or vertex causes connected faces to be hidden.

UV Selection Flushing

Selection setting functions flush down (unless the _noflush(...) version is used), this means selecting a face also selects all verts & edges, selecting an edge selects its vertices.

However it's expected the selection is flushed, de-selecting a vertex or edge must de-select it's faces (flushing up). For this, there are various flushing functions, exactly what is needed depends on the selection operation performed and the selection mode.

There are also situations that shouldn't be allowed such as a single selected vertex in face select mode.

Flushing & Synchronizing

Properly handling the selection state is important for operators that adjust the UV selection. This typically involves the following steps:

  • The UV selection changes.
  • The UV selection must be flushed between elements to ensure the selection is valid, (see: BM_mesh_uvselect_flush_* & BM_mesh_uvselect_mode_flush_* functions).
  • The UV selection must be synchronized to the mesh selection (see #BM_mesh_uvselect_sync_to_mesh).
  • The mesh must then flush selection to its elements (see: BM_mesh_select_flush_* & BM_mesh_select_mode_flush_* functions).

Valid State

For a valid state:

  • A selected UV-vertex must have its underlying mesh vertex selected.
  • A selected mesh-vertex must have at least one UV-vertex selected.

This is mostly true for edges/faces too, however there cases where the UV selection causes an edge/face to be selected in mesh space but not UV space.

See #BM_mesh_uvselect_is_valid for details.

Clearing the Valid State

As already noted, tools should maintain the synchronized UV selection where possible. However when this information isn't needed it should be cleared aggressively (see #BM_mesh_uvselect_clear), since it adds both computation & memory overhead.

For actions that overwrite the selection such as selecting or de-selecting all, it's safe to "clear" the data, other actions such as adding new geometry that replaces the selection can also safely "clear" the UV selection.

In practice users modeling in the 3D viewport are likely to clear the UV selection data since selecting the mesh without extending the selection is effectively a "De-select All". So the chances this data persists when it's not needed over many editing operations are low.

Definition in file bmesh_uvselect.hh.