The best way to programmatically store and reload a NVIDIA Mosaic topology


I’m the author of DisplayMagician, and a Public API user.

DisplayMagician is designed to record your display layout and configuration, and to apply that same layout when you want it in the future. It is a display layout record/apply program. It is not designed to make any changes to the layout, simply to record the existing layout as a display profile, and it allows you to change your display layout to any of your saved display profiles.

DisplayMagician works with NVIDIA video cards like this, when it is swapping between display profiles:

  • Disable any custom NVIDIA colour/HDR overrides (using NVAPI)
  • Disable any Mosaic topology if it is not in the wanted layout, or create a new Mosaic topology if it is in the new layout (using NVAPI)
  • Re-arrange the displays, enabling or disabling screens as needed (using Windows CCD API)
  • Enable windows colour/HDR settings (using Windows CCD API)
  • Enable any custom NVIDIA colour/HDR overrides for the new layout (using NVAPI)

My question is this: At the moment I programmatically create a new Mosaic topology each time that I want Mosaic to be enabled. Is this the best way to do it?

At the back of my head, I’m wondering if I should be doing it differently. Rather than dumping and storing the full Mosaic topology as I do now, should I simply be looking up the topology in the topology database, and just disabling/enabling it?

Does the NVIDIA Control Panel create a topology and store it in the driver database when a user enables a new surround layout? Does it create a display layout ID somewhere that I can store, so I can choose that same display layout later? If so, what should I how do I lookup what the display layout ID is? Should I be using the DRS APIS (NVAPI Reference Documentation)?

I really want to make sure that I’m doing it the recommended way so I avoid breaking changes when the NVIDIA driver is updated.


1 Like

Dear @terry.macdonald

Thank you for contacting NVIDIA developer forum.
We have sent your query to the respective team for details and we will get back to you on same.

NVAPI Forum Moderator

Further to the above, I should mention that I’m currently using a ‘SetDisplayGrid’ function call to turn on the surround mode. This appears to work for most of my users, but it doesn’t work for some users. They tend to have older hardware.

I have seen that nvapiwrapper c# library uses ‘SetCurrentTopo’ to turn on surround mode. What’s the correct way to do it? SetCurrentTopo or

I should mention that my program grabs the current mosaic configuration using GetCurrentTopo, and then it stores that configuration for later use.

Can I just apply the same TopoBrief and the MosaicDisplaySetting, overlap X and overlap y I grabbed previously from GetCurrentTopo in SetCurrentTopo then it will work? Or do I need to tweak the TopoBrief in some way? SetCurrentTopo not working for me at the moment as it complains the current topo is not possible (even though I just grabbed the mosaic configuration just before, then turned off surround mode, and tried to apply the mosaic configuration then)


I decided to pivot a little in the design, as I saw a comment in the NVAPI library that in order to turn off mosaic, I should set the DisplayGrid to a 1x1 display grid layout. I’ve been trying to do that as part of my testing, but I cannot generate the correct 1x1 display grid to be able to turn off Mosaic.

Can you please provide some example code showing how to use the 1x1 display grid to turn off Mosaic mode? I need it to show how to go from a 3 screen mosaic topology to a 3 single display display. Any help you can give will be greatly appreciated.