Troubleshooting - ApertureViewer/Aperture-Viewer GitHub Wiki

Troubleshooting & FAQ - Aperture Viewer

This page provides solutions to common problems, answers frequently asked questions, and directs you to resources for further assistance with Aperture Viewer.

[!IMPORTANT] Before seeking further support, please ensure you have:

  1. Read through the relevant sections of this FAQ.
  2. Checked that your system meets the System Requirements (especially the AVX processor requirement for Windows).
  3. Updated your graphics card drivers to the latest version from NVIDIA, AMD, or Intel. This is the most common solution for many visual and performance issues.
  4. Considered performing a Clean Install if you are upgrading or experiencing persistent strange behavior.

Common Issues & Solutions

1. Viewer Crashing on Startup or Shortly After Login

  • Most Common Cause: Outdated graphics card drivers.
    • Solution: Visit your graphics card manufacturer's website (NVIDIA, AMD, Intel) and download/install the latest stable drivers for your specific GPU model and operating system. Restart your computer after installation.
  • System Not Meeting Requirements:
    • Solution: Verify your PC meets the AVX CPU requirement (for Windows builds) and has a compatible graphics card. See System Requirements.
  • Corrupted Settings/Cache:
    • Solution: Perform a Clean Install. This involves backing up critical data (like chat logs if desired), uninstalling, manually deleting Aperture Viewer's settings and cache folders from your AppData/LocalAppData directories, and then reinstalling.
  • Software Conflicts: Rare, but other background software could interfere.
    • Solution: Try temporarily closing other non-essential applications to see if the issue persists.

2. Poor Performance / Low FPS (Frames Per Second)

  • Graphics Settings Too High:
    • Solution:
      • Lower your selected Aperture Graphics Preset level via the APS Gen Tab. Start with a lower level like "Basic HDR & Effects" or "Shadows" and see if performance improves.
      • Manually reduce demanding settings in APS: Lower Shadow Resolution/Clarity, reduce SSAO Samples/Scale, disable or lower settings for Reflections (SSR/Mirrors), decrease Draw Distance, lower Particle Count.
  • Outdated Graphics Drivers:
    • Solution: Update your graphics drivers (see point 1).
  • Hardware Limitations:
    • Solution: Your system might be struggling with the demands of modern Second Life rendering. Ensure you meet at least the recommended system requirements. Running at lower graphics settings may be necessary.
  • Crowded Areas / High Avatar Complexity:
    • Solution:
      • In APS Ava Tab, reduce "Max Complx" or "Avatar Count."
      • Consider using "Avatar Display" modes like "Limit by Complexity" or "Only Show Friends."
      • Temporarily disable "Show Avatars" entirely via the Ava tab for extreme situations.
  • Specific Aperture v1.0.0 FPS Limiter Note:
    • Aperture Viewer defaults to a 30 FPS limit and VSync ON in many presets to ensure smooth performance and mitigate potential upstream issues. You can adjust the "Max FPS" and "Enable FPS Limit" on the APS Gen Tab if your system can handle higher rates consistently.

3. Visual Glitches (Incorrect Textures, Flickering, Artifacts)

  • Outdated Graphics Drivers:
    • Solution: Update your graphics drivers.
  • Corrupted Cache:
    • Solution: Perform a Clean Install, ensuring you delete the cache folders.
  • Specific Known Issues (v1.0.0):
    • SSAO/SSR on Water: Grid-like artifacts or "acne" can sometimes appear on water surfaces when SSAO and/or SSR are enabled. This is an underlying viewer issue being investigated for future fixes.
      • Workaround: Try adjusting SSR settings (e.g., Ray Step, Iterations on the APS Refl Tab) or temporarily disabling SSAO/SSR if the artifacts are too distracting on water.
    • SSR in Snapshots: Screen Space Reflections may not appear correctly in saved snapshots.
      • Status: A fix for this is planned for an upcoming release.

4. Problems with Aperture Phototools Suite (APS) Settings

  • Settings Don't Seem to Apply or Reset Unexpectedly:
    • Graphics Presets Interaction: Remember that selecting one of the built-in Aperture Graphics Presets (Levels 0-8 via the Gen Tab) WILL reset most rendering settings and Post-Processing settings to the defaults for that level.
      • Solution: If you have a custom look, save it as a Comprehensive Custom Preset using the "Graphic Presets: Save" button at the bottom of APS before changing built-in levels. You can then reload your custom preset.
  • Camera Roll Not Saving with Camera Presets (v1.0.0 specific):
    • Issue: Camera roll may not save/load correctly with the "Viewer Camera" presets in APS.
    • Status: This is a known bug in v1.0.0 and is scheduled to be fixed in an upcoming hotfix. Roll for Flycam presets is also under review for accuracy.

5. Login Issues

  • Solution:
    1. Double-check your username and password (case-sensitive).
    2. Verify the selected grid is correct (Second Life vs. an OpenSim grid).
    3. Check your internet connection.
    4. Check the status page for Second Life or your OpenSim grid for outages.
    5. Temporarily disable your firewall/antivirus for testing (ensure you re-enable it and add an exception for Aperture Viewer if this helps).

Frequently Asked Questions (FAQ)

  • Q: Is Aperture Viewer available for Mac or Linux?

    • A: Currently, the official v1.0.0 release of Aperture Viewer is for Windows 64-bit systems with AVX support only. While the codebase is derived from Firestorm which supports Mac/Linux, significant adaptation and dedicated build efforts would be required for official Aperture releases on these platforms. This is a potential future goal but is not currently available.

  • Q: Where are my custom APS Graphics Presets saved?

    • A: They are saved as .xml files in your user settings folder, typically: C:\Users\[YourUserName]\AppData\Roaming\ApertureViewer\user_settings\graphics_presets (on Windows).

  • Q: How is Aperture Viewer different from Firestorm Viewer?

    • A: While Aperture is built on the Firestorm codebase, it has a distinct focus on visual creators. Key differences include the exclusive Aperture Phototools Suite (APS) with its real-time Post-Processing pipeline, the procedural starfield, performance-tuned graphics levels, comprehensive custom preset system, unique UI themes, and various other creator-focused enhancements and optimizations. See the Viewer Features Overview page for more details.

  • Q: Why does Aperture Viewer default to 30 FPS in some presets?

    • A: This is to provide a smooth, consistent experience for a wider range of hardware and to mitigate potential underlying performance variability. Users with capable systems can easily adjust this via the APS Gen Tab.

  • Q: Can I use my Firestorm settings with Aperture Viewer?

    • A: While some settings might carry over if you attempt to copy settings folders (not generally recommended without a full understanding), Aperture Viewer has its own unique settings and featuretable_aperture.txt. For the best experience and to avoid conflicts, a fresh setup or using Aperture's backup/restore for its own settings is advised. A Clean Install is often best when switching.

Reporting Bugs and Getting Further Help

If your issue is not covered in this FAQ or by searching existing documentation, please follow these steps to get assistance:

  1. Search Existing GitHub Issues First:

    • Before anything else, please thoroughly search our GitHub Issues Tracker.
    • Check both open and closed issues to see if your problem or a similar one has already been reported, discussed, or resolved. This can often provide an immediate solution and saves everyone time.

  2. Join our Discord for Discussion & Live Support (If No Existing Issue Found):

    • If you cannot find a solution in the existing GitHub Issues, the next best step is to join our official Aperture Viewer Discord Server.
    • Invite Link: https://discord.gg/rVmPcUgF7Z
    • On Discord, you can:
      • Ask general questions.
      • Discuss the issue you're experiencing with the community and development team.
      • Get live troubleshooting assistance.
      • Often, if your issue is confirmed as a new bug or requires formal tracking, a team member may guide you on creating a GitHub Issue or even create one for you based on the discussion.

  3. Report a New Bug on GitHub (If Guided or for Complex Issues):

    • If, after discussing on Discord, it's determined that your issue is a new bug requiring formal tracking, or if your issue is complex and best detailed in writing, please create a new bug report on our GitHub Issues Tracker.
    • Please provide as much detail as possible, including:
      • Aperture Viewer Version (e.g., v1.0.0).
      • Your Operating System & Version (e.g., Windows 11 Pro 22H2).
      • Graphics Card Model & Driver Version (e.g., NVIDIA RTX 4080, Driver 555.99).
      • Clear, step-by-step instructions to reproduce the bug.
      • What you expected to happen versus what actually happened.
      • Screenshots or short videos if they help illustrate the problem.
      • Relevant portions of your viewer log file. This can usually be found at:
        • Windows: C:\Users\[YourUserName]\AppData\Roaming\ApertureViewer\logs\ApertureViewer.log (You may need to enable "Show hidden files and folders" to see the AppData folder.)
    • Linking back to any relevant Discord discussion can also be helpful.

Thank you for using Aperture Viewer and for helping us improve it by following these support steps!