docs: remove outdated rendering fix summary and update documentation for wireframe approach
This commit is contained in:
MayaTheShy
@@ -1,216 +0,0 @@
|
||||
# Starworld Rendering Pipeline Fix Summary
|
||||
|
||||
## Problem Diagnosis
|
||||
|
||||
The Starworld project stopped rendering entities after attempting to implement 3D model and texture support. The root cause was using incorrect Stardust API patterns that don't exist in the current version:
|
||||
|
||||
### Issues Found:
|
||||
|
||||
1. **Incorrect Model API Usage**
|
||||
- Used `Model::namespaced("fusion", "tex_cube")` which doesn't exist
|
||||
- Attempted to use `ModelPart::new()` and `.mat_param()` which are server-side APIs, not available in the client asteroids library
|
||||
|
||||
2. **API Mismatch**
|
||||
- Confused server-side Model implementation with client-side asteroids Elements
|
||||
- The `Model` element in asteroids requires a file path via `Model::direct(PathBuf)`
|
||||
- Material parameters are not directly accessible from client code
|
||||
|
||||
3. **Asset Pipeline Missing**
|
||||
- Overte provides model URLs (HTTP), but Stardust's `Model::direct()` expects local file paths
|
||||
- No asset download/caching mechanism was implemented
|
||||
|
||||
## Solution Implemented
|
||||
|
||||
### 1. **Switched to Wireframe Rendering**
|
||||
|
||||
Instead of trying to use non-existent model APIs, the fix implements proper wireframe visualizations using the Stardust `Lines` element, which is well-supported and documented:
|
||||
|
||||
```rust
|
||||
// Box entities - 12-edge cube wireframe
|
||||
let cube_lines = create_wireframe_cube(node_color, 0.005);
|
||||
Spatial::default()
|
||||
.transform(transform)
|
||||
.build()
|
||||
.child(Lines::new(cube_lines).build())
|
||||
|
||||
// Sphere entities - 3 orthogonal circles
|
||||
let sphere_lines = create_wireframe_sphere(node_color, 0.005);
|
||||
Spatial::default()
|
||||
.transform(transform)
|
||||
.build()
|
||||
.child(Lines::new(sphere_lines).build())
|
||||
|
||||
// Model entities - octahedron placeholder
|
||||
let oct_lines = create_octahedron_wireframe(node_color, 0.005);
|
||||
Spatial::default()
|
||||
.transform(transform)
|
||||
.build()
|
||||
.child(Lines::new(oct_lines).build())
|
||||
```
|
||||
|
||||
### 2. **Cleaned Up Dependencies**
|
||||
|
||||
Removed unused imports:
|
||||
- `Model` and `ModelPart` from asteroids (not needed for wireframe approach)
|
||||
- `Transform` (already using fully qualified path)
|
||||
- `MaterialParameter` (not available in client API)
|
||||
- `ResourceID` (not needed for current implementation)
|
||||
|
||||
### 3. **Updated Cargo Configuration**
|
||||
|
||||
Changed from path-based dependency (non-existent local asteroids) to git-based:
|
||||
```toml
|
||||
[dependencies.stardust-xr-asteroids]
|
||||
git = "https://github.com/StardustXR/asteroids.git"
|
||||
branch = "dev"
|
||||
```
|
||||
|
||||
## Current Rendering Capabilities
|
||||
|
||||
✅ **Working:**
|
||||
- Box entities render as colored wireframe cubes
|
||||
- Sphere entities render as 3-circle wireframe spheres
|
||||
- Model entities render as octahedron wireframes (distinct placeholder)
|
||||
- All entities respect:
|
||||
- Position, rotation, scale (transform)
|
||||
- RGB color with alpha
|
||||
- Dimensions (xyz size)
|
||||
- Entity type differentiation
|
||||
|
||||
❌ **Not Yet Implemented:**
|
||||
- Loading actual 3D models from Overte URLs
|
||||
- Applying textures to surfaces
|
||||
- Solid surface rendering
|
||||
|
||||
## Build Status
|
||||
|
||||
✅ **Bridge compiles successfully** (warnings resolved)
|
||||
```bash
|
||||
cd bridge
|
||||
cargo build
|
||||
# Output: Finished `dev` profile [unoptimized + debuginfo] target(s) in 2.01s
|
||||
```
|
||||
|
||||
## How to Test
|
||||
|
||||
### 1. Build the Bridge
|
||||
```bash
|
||||
cd /home/mayatheshy/stardust/Starworld
|
||||
cd bridge
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
### 2. Build the C++ Client
|
||||
```bash
|
||||
cd /home/mayatheshy/stardust/Starworld
|
||||
mkdir -p build && cd build
|
||||
cmake ..
|
||||
make
|
||||
```
|
||||
|
||||
### 3. Run with Simulation Mode
|
||||
```bash
|
||||
export STARWORLD_SIMULATE=1
|
||||
export STARWORLD_BRIDGE_PATH=/home/mayatheshy/stardust/Starworld/bridge/target/debug
|
||||
./stardust-overte-client
|
||||
```
|
||||
|
||||
This will create three demo entities:
|
||||
- **CubeA**: Red wireframe cube (20cm)
|
||||
- **SphereB**: Green wireframe sphere (15cm)
|
||||
- **ModelC**: Blue octahedron (25cm)
|
||||
|
||||
### 4. Connect to Real Overte Server
|
||||
```bash
|
||||
export STARWORLD_BRIDGE_PATH=/home/mayatheshy/stardust/Starworld/bridge/target/debug
|
||||
./stardust-overte-client ws://domain.example.com:40102
|
||||
```
|
||||
|
||||
## Path to Full 3D Model Support
|
||||
|
||||
To implement true 3D model rendering, you would need:
|
||||
|
||||
### Phase 1: Asset Management
|
||||
1. **Model Downloader Service**
|
||||
- Background thread/async task to download models from Overte URLs
|
||||
- Cache to local filesystem (e.g., `~/.cache/starworld/models/`)
|
||||
- Track download progress and completion
|
||||
|
||||
2. **URL to Path Mapping**
|
||||
- Hash Overte URLs to generate cache filenames
|
||||
- Maintain a registry: `HashMap<String, PathBuf>` (URL -> local path)
|
||||
- Handle re-downloads on cache miss
|
||||
|
||||
### Phase 2: Dynamic Scene Updates
|
||||
3. **Placeholder → Model Replacement**
|
||||
- Initially render wireframe placeholder
|
||||
- When model download completes, update the scene:
|
||||
```rust
|
||||
if let Some(local_path) = model_cache.get(&node.model_url) {
|
||||
Model::direct(local_path)
|
||||
.transform(transform)
|
||||
.build()
|
||||
} else {
|
||||
// Wireframe placeholder while downloading
|
||||
Lines::new(octahedron_lines).build()
|
||||
}
|
||||
```
|
||||
|
||||
4. **Texture Application**
|
||||
- Download textures to cache similarly
|
||||
- Use model part API to apply materials (requires deeper asteroids integration)
|
||||
|
||||
### Phase 3: Format Conversion (if needed)
|
||||
5. **Overte → GLTF Conversion**
|
||||
- If Overte uses proprietary formats, implement converter
|
||||
- Or use Overte's existing export capabilities
|
||||
|
||||
## Example: Working Model Loading Pattern
|
||||
|
||||
From the Armillary project (reference implementation):
|
||||
```rust
|
||||
match Model::direct(&self.model_path) {
|
||||
Ok(model_elem) => {
|
||||
model = Some(
|
||||
model_elem
|
||||
.pos([0.0, model_info.height_offset, 0.0])
|
||||
.build()
|
||||
.identify(&model_info.uuid),
|
||||
)
|
||||
}
|
||||
Err(e) => {
|
||||
// Fallback to error text display
|
||||
model_error = Some(
|
||||
Text::new(format!("Model Error:\n{e}"))
|
||||
.character_height(0.025)
|
||||
.build(),
|
||||
)
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
**Key takeaway:** `Model::direct()` requires a valid local `PathBuf`, not a URL.
|
||||
|
||||
## Conclusion
|
||||
|
||||
The rendering pipeline is now **functional and stable** with wireframe visualizations. This provides:
|
||||
- Immediate feedback during development
|
||||
- Low overhead for debugging entity positions/transforms
|
||||
- Clear visual distinction between entity types
|
||||
- Foundation for future 3D model integration
|
||||
|
||||
To enable full 3D models, implement the asset pipeline described above. The wireframe approach will continue to work as a fallback for failed downloads or unsupported model formats.
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. **bridge/src/lib.rs** - Fixed `reify()` implementation to use Lines instead of non-existent Model APIs
|
||||
2. **bridge/Cargo.toml** - Changed asteroids dependency from path to git
|
||||
3. **ENTITY_RENDERING_ENHANCEMENTS.md** - Updated documentation to reflect wireframe approach
|
||||
|
||||
## Build Artifacts
|
||||
|
||||
After building, the bridge library will be at:
|
||||
- Debug: `bridge/target/debug/libstardust_bridge.so`
|
||||
- Release: `bridge/target/release/libstardust_bridge.so`
|
||||
|
||||
The C++ client will dynamically load this at runtime.
|
||||
Reference in New Issue
Block a user