b3dVertexNormal

Sets vertex normal vector (with NY negation for lighting). Takes mesh (surface-based mesh entity), surface (surface handle, 0-based), vertexIndex (vertex number, 0-based), nx/ny/nz (normal components as doubles, should form unit vector). Returns nothing. Validates mesh exists, type is ENTITY_MESH, is surface-based, surface index valid, and vertex index valid. Sets normal: normal.x = nx, normal.y = -ny (negated), normal.z = nz. Sets surface->needsGPUUpload=true and mesh->needsGPUUpload=true. Silently returns on validation errors.

This function sets vertex normal for custom lighting control. Normal = surface direction vector used for lighting calculations (dot product with light direction determines brightness). CRITICAL: NY negation applied - user NY+ = up converted to DirectX NY- = up internally. User sets normal (0, 1, 0) for upward-pointing, stored as (0, -1, 0) internally. Normal should be unit vector: magnitude Sqr(nx^2 + ny^2 + nz^2) ~ 1.0, but not enforced (non-unit normals cause incorrect lighting). Must lock mesh before calling. Use cases: (1) Hard edges (duplicate vertices with different normals for sharp creases), (2) Custom lighting (artistic normal direction for stylized shading), (3) Normal smoothing (average normals across shared vertices), (4) Flat shading (all vertices in triangle get same normal), (5) Override b3dUpdateNormals results. Common pattern: b3dLockMesh(mesh), v0=b3dAddVertex(...), v1=b3dAddVertex(...), v2=b3dAddVertex(...), calculate face normal via cross product, b3dVertexNormal(mesh, surf, v0, nx, ny, nz), b3dVertexNormal(mesh, surf, v1, nx, ny, nz), b3dVertexNormal(mesh, surf, v2, nx, ny, nz) for flat shading, b3dUnlockMesh(mesh). NY negation symmetry: b3dVertexNY negates on output, b3dVertexNormal negates on input - round-trip consistent. Normal range: typically -1.0 to +1.0 per component for unit vector. GPU upload deferred: changes applied on b3dUnlockMesh. Alternative: b3dUpdateNormals for automatic calculation. Hard edge technique: duplicate vertex at seam position, assign different normal to each copy. Performance: O(1) per vertex. Lighting impact: normal affects diffuse/specular calculations, incorrect normals cause dark/bright spots. Precision: double input, float storage.