b3dGetEntityRoughnessFX

Returns entity roughness PBR property (0.0-1.0 double). Takes entity (mesh entity handle, positive integer). Returns double roughness value (0.0=perfectly smooth/mirror to 1.0=completely rough/matte, -1.0 on error). Queries roughness property from entity material for physically-based rendering, checks material override first then base material.

Roughness meaning: 0.0=perfectly smooth (mirror reflection, sharp highlights, polished surfaces), 0.2-0.4=smooth (glossy plastic, polished wood, wet surfaces), 0.5-0.7=moderate (dry wood, concrete, worn metal), 0.8-1.0=rough (matte paint, fabric, sandpaper, chalk). Controls specular highlight size and reflection clarity (low roughness=tight highlights, high roughness=broad soft highlights).

Material source: checks entity.materialOverrideIndex first (if >= 0 uses per-entity override material), falls back to entity.mesh->materialIndex (shared mesh material), reads material.roughnessFactor field.

PBR rendering impact: roughness=0.0 produces mirror-like reflections (sharp specular highlights, clear environment reflections), roughness=1.0 produces matte appearance (broad diffuse-like highlights, blurred reflections), affects microfacet distribution (GGX/Trowbridge-Reitz model in shader), combines with metallic for material definition (smooth metal=chrome, rough metal=brushed steel).

Use cases: (1) Query surface finish (read roughness for material identification), (2) Material restoration (save roughness before modification, restore later), (3) Dynamic weathering (increase roughness over time for aging effect), (4) Material validation (check if surface configured as glossy or matte), (5) Visual effects (query roughness for shader adjustments or particle reflectivity).

Common patterns: save roughness = oldRoughness#=b3dGetEntityRoughnessFX(entity%); check finish = If b3dGetEntityRoughnessFX(entity%)<0.3 Then glossy Else matte; weather effect = roughness#=b3dGetEntityRoughnessFX(entity%): newRoughness#=roughness#+weatherSpeed#: If newRoughness#>1.0 Then newRoughness#=1.0: b3dSetEntityRoughnessFX(entity%, newRoughness#); interpolate = current#=b3dGetEntityRoughnessFX(entity%): new#=current#+(target#-current#)*speed#: b3dSetEntityRoughnessFX(entity%, new#).

Typical values: polished metal=0.0-0.1 (mirror-like), glossy paint=0.2-0.3 (shiny car paint), plastic=0.3-0.5 (varies by finish), wood=0.5-0.7 (depends on varnish), stone=0.7-0.9 (natural matte), fabric=0.9-1.0 (completely diffuse).

Return values: -1.0 on error (invalid entity handle, non-mesh entity, prints error to stderr), 0.5 if mesh has no material (default PBR value), 0.0-1.0 actual roughness value (from material.roughnessFactor field).

Performance: very fast O(1) lookup (simple material field access, ~0.0001ms), no calculation or GPU access required, suitable for per-frame queries.

Material override awareness: reads from correct material layer (override if exists, else base material), consistent with b3dSetEntityRoughnessFX behavior (set and get use same material source).

PBR workflow: metallic/roughness workflow (used by BambooBasic), stores roughness in material.roughnessFactor (0.0-1.0), optionally combined with metallicRoughnessTexture (texture.g=roughness, texture.b=metallic).

Specular highlight: low roughness=small tight highlights (pin-point reflections), high roughness=large soft highlights (broad sheen), affects both direct lighting and environment reflections.

Related: b3dSetEntityRoughnessFX sets roughness value, b3dGetEntityMetallicFX reads metallic property, b3dSetEntityMetallicFX sets metallic, b3dGetEntityAlphaFX/ColorFX read baseColor properties.