docs: document adapter_name requirement for multi-GPU NVIDIA setups

[kabooHD]

Description

Adds troubleshooting guidance for users with multiple NVIDIA GPUs who encounter dmabuf import failures with capture = wlr. Provides commands for identifying the correct render node and explains the symptoms.

Refs #5023

Screenshot

Issues Fixed or Closed

Roadmap Issues

Type of Change

• feat: New feature (non-breaking change which adds functionality)
• fix: Bug fix (non-breaking change which fixes an issue)
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semicolons, etc.)
• refactor: Code change that neither fixes a bug nor adds a feature
• perf: Code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Other changes that don't modify src or test files
• revert: Reverts a previous commit
• BREAKING CHANGE: Introduces a breaking change (can be combined with any type above)

Checklist

• Code follows the style guidelines of this project
• Code has been self-reviewed
• Code has been commented, particularly in hard-to-understand areas
• Code docstring/documentation-blocks for new or existing methods/components have been added or updated
• Unit tests have been added or updated for any new or modified functionality

AI Usage

• None: No AI tools were used in creating this PR
• Light: AI provided minor assistance (formatting, simple suggestions)
• Moderate: AI helped with code generation or debugging specific parts
• Heavy: AI generated most or all of the code changes

[ReenigneArcher]

Thank you for the PR; however I don't think this adds much value over what we already have in the docs at https://docs.lizardbyte.dev/projects/sunshine/master/md_docs_2configuration.html?lng=en#adapter_name

[kabooHD]

@ReenigneArcher

Thanks for the quick review. I'd like to push back gently on this one.

The existing docs at the link cover what adapter_name does as a configuration option — but they don't help a user diagnose when they need to set it. The current description ("Sunshine will select the default video card") doesn't suggest that selection can go wrong, or hint at what symptoms indicate it has.

For context on why this matters: I spent three days debugging this on a dual RTX 5090 system (NixOS, Hyprland, NVIDIA open driver). The symptoms were a black stream, repeated Failed to create buffer from params errors in the Sunshine log, and ~30 GB of VRAM filling on the wrong GPU within ~20 seconds of every Moonlight connect. I had DRI_PRIME and CUDA_VISIBLE_DEVICES correctly pinned to the right GPU; the wlr capture path ignored both. I read the configuration docs multiple times during debugging and didn't connect "select the default video card" to my symptoms — there was no path from the error message to the fix.

A user hitting this failure will search the error string, not browse the configuration reference. The troubleshooting page is where that search would land. The PR adds a symptom-to-fix mapping that the reference page intentionally doesn't provide, which is exactly the role troubleshooting docs serve.

If the format isn't what you'd like — too long, wrong section, too NVIDIA-specific — happy to revise. If you'd rather not have it at all, I understand, and I'll leave the issue I filed in place so the next person can at least find it via search.

Again thank you :)

[ReenigneArcher]

1. I think this problem should probably be fixed, or at least logged better, in the actual code. At a minimum we should probably detect how many devices there are, and if multiple tell the user they should probably define which one they want to use in the config.
2. I'm not a fan of AI generated user facing docs. Especially then linking back to another AI generated source (the github issue). Not to mention the way it linked, won't even work in our docs and will just render as #5023.
3. I'm not sure the symptoms described are exclusive to the problem you faced, which would lead users down a rabbit whole trying this solution that could be for a completely separate problem. "black screen" for example is probably the most common issue users face and there are many causes of it.

This doesn't mean I won't accept a different version of this PR, but as is I think it's not of high value. I'll re-open the PR in case you want to re-work it.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[kabooHD]

Closing this. #5030 is fixing the underlying bug properly in code, so the docs workaround isn't needed. I also attempted to help test #5030 directly, but building the fork on NixOS turned into a bigger project than I had skills or time for, so I'll wait for it to merge and verify on my system once it reaches nixpkgs.
Thanks for the review — the feedback on scope and voice was fair, and pointing me toward the code fix was the right call.