k3d

Lighting System Specification (Implemented)

Overview

The lighting system provides configurable illumination for the 3D scene with real-time adjustment capabilities and persistence.

1. Lighting Components

1.1 Directional Light

• Main Light Source: Primary directional illumination
• Configurable Intensity: Adjustable brightness (0.0-1.0 range)
• Configurable Color: RGB color with alpha control
• Direction: Fixed direction (-0.5, -1.8, -1.2 normalized)
• Shadow Casting: Integrated with shadow mapping system

1.2 Ambient Light

• Global Illumination: Uniform scene lighting
• Configurable Intensity: Adjustable brightness (0.0-1.0 range)
• Configurable Color: RGB color with alpha control
• Environmental Effect: Simulates indirect lighting

1.3 Specular Light

• Highlight Control: Adjustable specular intensity
• Configurable Intensity: Adjustable brightness (0.0-1.0 range)
• Configurable Color: RGB color with alpha control
• Material Interaction: Affects shiny surface appearance

2. Shadow System

2.1 Shadow Mapping

• Directional Shadow Light: Single directional shadow source
• Shadow Map Resolution: 8192×8192 texture
• Shadow Coverage: 60° field of view, 300 unit range
• Shadow Quality: Configurable parameters

2.2 Shadow Parameters

• Shadow Bias: Adjustable (default: 365.0)
• Shadow Normal Bias: Adjustable (default: 5620.0)
• PCF Mode: Configurable filter size (default: 1)
• Shadow Dither: Toggle for dithering effect
• CSM Support: Cascaded shadow maps toggle

2.3 Shadow Rendering

• Depth Pass: Separate shadow map generation
• Shadow Sampling: Custom shader integration
• Shadow Blending: Smooth shadow transitions
• Performance: Optimized for real-time interaction

3. Lighting Controls

3.1 UI Integration

• Lighting Panel: Dedicated UI panel for lighting control
• Real-time Sliders: Immediate visual feedback
• Preset Values: Default lighting configurations
• Panel Toggle: Show/hide via toolbar button

3.2 Control Parameters

• Shadow Light Value: 0.0-1.0 range (default: 0.59)
• Shadow Light Alpha: 0.0-1.0 range (default: 0.5)
• Directional Light Value: 0.0-1.0 range (default: 0.73)
• Directional Light Alpha: 0.0-1.0 range (default: 1.0)
• Ambient Light Value: 0.0-1.0 range (default: 0.59)
• Ambient Light Alpha: 0.0-1.0 range (default: 1.0)
• Specular Light Value: 0.0-1.0 range (default: 0.2)
• Specular Light Alpha: 0.0-1.0 range (default: 0.95)

4. Shader Integration

4.1 Custom Shader Pipeline

• GLSL Shaders: Custom vertex and fragment shaders
• Material Support: Diffuse, specular, ambient components
• Lighting Calculations: Per-pixel lighting computations
• Shadow Sampling: Custom shadow map sampling

4.2 Shader Provider

• SketchShaderProvider: Custom shader management
• Uniform Parameters: Light positions, colors, intensities
• Shadow Parameters: Bias, PCF size, dither toggle
• Performance: Optimized shader compilation

4.3 Rendering Pipeline

• Shadow Pass: Depth-only rendering for shadow map
• Main Pass: Full lighting with shadow sampling
• Transparency: Blending for selected elements
• Culling: Front/back face culling optimization

5. Persistence

5.1 Serialization

• JSON Format: Lighting parameters stored in model file
• Default Values: Safe defaults for new models
• Version Compatibility: Backward compatibility handling
• Automatic Migration: Older files get updated values

5.2 File Structure

{
  "lighting": {
    "shadowLightValue": 0.59,
    "shadowLightAlpha": 0.5,
    "directionalLightValue": 0.73,
    "directionalLightAlpha": 1.0,
    "ambientLightValue": 0.59,
    "ambientLightAlpha": 1.0,
    "specularLightValue": 0.2,
    "specularLightAlpha": 0.95
  },
  "shadows": {
    "shadowBias": 365.0,
    "shadowNormalBias": 5620.0,
    "pcfMode": 1,
    "dither": false,
    "useCsm": true
  }
}

6. User Interaction

6.1 UI Controls

• Sliders: Precise value adjustment
• Toggle Buttons: Shadow enable/disable
• Preset Buttons: Quick lighting configurations
• Real-time Preview: Immediate visual feedback

6.2 Keyboard Shortcuts

• L: Toggle lighting panel visibility
• Shift-L: Reset to default lighting
• Ctrl-L: Cycle through lighting presets

6.3 Visual Feedback

• Light Direction: Visual indicator in scene
• Shadow Coverage: Shadow frustum visualization
• Light Intensity: Color-coded indicators

7. Performance Considerations

7.1 Optimization Techniques

• Shadow Map Reuse: Minimize shadow map regeneration
• Light Culling: Only process visible lights
• Shader Optimization: Efficient GLSL code
• Batch Rendering: Minimize draw calls

7.2 Performance Targets

• 60 FPS Minimum: Smooth interaction requirement
• Shadow Quality: Balanced quality/performance
• Mobile Considerations: Future mobile compatibility

8. Future Enhancements

8.1 Planned Features

• Multiple Lights: Support for additional light sources
• Point Lights: Localized illumination sources
• Spot Lights: Directional localized lighting
• Light Probes: Advanced global illumination

8.2 Advanced Features

• Light Animation: Dynamic lighting effects
• Light Templates: Reusable lighting setups
• Environment Maps: Reflection and refraction
• Volumetric Lighting: Light scattering effects

9. Acceptance Criteria

1. Visual Quality: Lighting should provide clear scene illumination
2. Performance: Lighting should not impact interaction smoothness
3. Shadow Quality: Shadows should be crisp and stable
4. UI Responsiveness: Controls should provide immediate feedback
5. Persistence: Lighting settings should save/load correctly

10. Implementation Notes

10.1 libGDX Integration

• Environment Class: Manages lighting parameters
• DirectionalLight: Primary light source
• DirectionalShadowLight: Shadow casting light
• Material System: Surface property management

10.2 Rendering Pipeline

• ModelBatch: Efficient model rendering
• DepthShaderProvider: Shadow map generation
• Custom Shaders: Advanced lighting effects
• Blend Attributes: Transparency handling

10.3 Performance Tips

• Shadow Map Size: Balance quality and performance
• PCF Samples: Adjust for quality vs performance
• Light Count: Limit active lights for mobile
• Shader Complexity: Optimize for target hardware

This site is open source. Improve this page.