b3dSetHandleBaseTexture

Sets base texture rotation/scale pivot point in UV space (0.0-1.0 range). Takes entityHandle (mesh entity), u (horizontal pivot 0.0-1.0), v (vertical pivot 0.0-1.0). Returns nothing. Sets material.baseTextureRotationPivot for texture transformations.

This function sets pivot point. Texture pivot: point around which texture rotates and scales, UV coordinates 0.0-1.0 (0.0=left/bottom, 1.0=right/top), default pivot is (0, 0) bottom-left corner, (0.5, 0.5) is center of texture. UV space: u = horizontal coordinate (0.0 = left edge, 1.0 = right edge), v = vertical coordinate (0.0 = bottom edge, 1.0 = top edge), independent of texture pixel dimensions, normalized coordinate system. Rotation pivot: b3dRotateTexture rotates around this pivot, (0, 0) pivot rotates around bottom-left corner, (0.5, 0.5) pivot rotates around center (most common), (1, 1) pivot rotates around top-right corner, affects rotation behavior visually. Scale pivot: texture scaling also uses this pivot, scaling from (0, 0) scales from bottom-left, scaling from (0.5, 0.5) scales from center (keeps centered), scaling from (1, 1) scales from top-right, combined with rotation for complex transformations. Use cases: (1) Centered rotation (u=0.5, v=0.5 for balanced spinning), (2) Corner rotation (u=0, v=0 for hinge effect), (3) Centered scaling (u=0.5, v=0.5 for zoom in/out), (4) Offset pivot (custom point for specialized effects), (5) Animated transformations (changing pivot for dynamic effects). Common patterns: centered operations = b3dSetHandleBaseTexture(entity, 0.5, 0.5), corner pivot = (0, 0) or (1, 1) for hinge/door effects, custom pivot = calculate based on feature position in texture, convenience = use b3dSetMidHandleBaseTexture for common case. Typical usage: call before b3dRotateTexture or b3dScaleTexture, set once if pivot doesn't change, default (0, 0) rarely desired for rotation, most rotations want centered pivot (0.5, 0.5), combine with transform functions for complete effect. Material targeting: sets entity material.baseTextureRotationPivot, affects material override if set, surface-based meshes update all surfaces, loaded meshes update default material, propagates via g_materialPropertiesDirty flag. Shader behavior: pivot used in shader texture matrix calculation, texture transforms applied in shader during sampling, matrix transforms UV coordinates before texture lookup, pivot determines transform origin in UV space. Transform order: transformations applied in order: scale -> rotate -> position, pivot affects scale and rotation (not position), all transforms combined into single matrix, matrix uploaded to GPU via material constant buffer. Default pivot: new materials default to (0, 0) pivot, not ideal for most use cases (rotation looks wrong), explicitly set pivot for expected behavior, or use b3dSetMidHandleBaseTexture for common centered case. Coordinate system: u axis runs left to right (like X), v axis runs bottom to top (like Y), matches standard UV mapping conventions, (0, 0) is bottom-left (OpenGL style, opposite of image coordinates). Examples: (0.5, 0.5) = center (most common for rotation), (0, 0) = bottom-left corner, (1, 1) = top-right corner, (0.5, 0) = bottom-center, (0, 0.5) = left-center, custom positions for specific texture features. Animation: can animate pivot for moving rotation center, combined with rotating texture creates complex motion, example: orbit effect by animating pivot in circle + rotating texture, or swinging pendulum by animating pivot position. Performance: negligible cost (simple field assignment), pivot stored in material, used during shader matrix calculation (minimal GPU cost), change triggers material upload (once per frame if changing). Validation: checks entity is valid mesh, prints error if invalid handle or not mesh, no validation for u/v values (any float accepted), values outside 0-1 work but give unusual behavior. Relationship to position/scale/rotation: pivot doesn't move texture (use b3dPositionTexture), pivot doesn't scale texture (use b3dScaleTexture), pivot doesn't rotate texture (use b3dRotateTexture), pivot controls WHERE rotation/scaling happens. Common mistake: forgetting to set pivot before rotation, rotation around (0, 0) looks wrong for most textures, always set pivot to (0.5, 0.5) for natural rotation unless specific corner needed. Related: b3dSetMidHandleBaseTexture sets pivot to center (0.5, 0.5), b3dRotateTexture rotates texture around pivot (uses this pivot), b3dScaleTexture scales texture from pivot (uses this pivot), b3dSetHandleDetailTexture sets pivot for detail textures (independent setting).