Confused: What API to use to add 3D Mouse support to our app

[szerbst]

Hi there

we are about to give the space mouse a try in our application. However, downloading the "SDK" and browsing some topics in this forum makes me wonder: What is the correct way to communicate with the space mouse?

I looked at the samples on the FTP and the sticky topics here. Most of them state something like that:

"Using this method bypasses the 3DxWare driver, so nothing your users will
do in that GUi will effect your application. That's a heavy tradeoff you must
consider."

Looking into the SDK I do not find any lib or dll or public header I can use to link some kind of "3D mouse API" to our application. Using the WM_INPUT or DirectInput seems to be possible but seems to involve writing all the code again that a 3D mouse driver should already contain. Plus you seem to ignore all the settings users apply in their Space Mouse control panel?

I am kinda lost here, I'm not even able to find the "Programming for the 3D Mouse.pdf" mentioned throughout the forum here.

Could someone please guide me how the "official" way is to add 3D mouse support to a custom C++ application while *not* ignoring settings users do in their 3dconnexion control panel and using the official drivers?

Thanks in advance,
Stefan

[szerbst]

There seems to have been an update to the download of the SDK during the last two weeks or my original download had been corrupted. I redownloaded it and now there is the PDF document mentioned above. My first download missed the "doc" folder antirely and just contained what is in the "samples" folder.

Anyway, my question remains: What is the recommended way to integrate 3D mouse support to ou application? As far as I read in this forum and the doc the Raw Input methode seems to be prefered. But if I get this right then this is Windows only while we need to support Linux as well. Also, the quote stated above about circumventing the 3D Connexion driver by using Raw Input remains valid as well.

This makes me even more confused ...

regards,
Stefan

[jwick]

Hello Stefan,

We have found that Raw Input (WM_INPUT) is the best way to go on Windows. It will result in a plug-n-play solution for your end-users, such that they don't need to install any other software than your application.

Being a Microsoft API, it is true that it doesn't exist on Linux.

It is also true that this circumvents the current driver. There is another one that is in beta that reestablishes that functionality. It will be available for beta to ISVs soon. BUT, we want your application to work w/o end users installing 3DxSoftware. It's much easier on them.

The Standard 3D Mouse SDK doc goes into the details.

3Dx Software Development

[szerbst]

Thanks for the fast reply.

I understand the advantages of not requiring any 3D Connexion software at the end users side if you are aiming at a standard for 3D input devices. But I was expecting an API implementation that certified software packages could ship along with their application.

Anyway, if we go with the Raw Input method what would be the recommended way to support the space mouse on Linux? The documents in the SDK download seem not to mention Linux at all.

regards,
Stefan

[jwick]

For Linux, we don't have a native solution. The Unix SDK should be used. It requires the end-user to install the 3Dx software.

For Windows, we recommend that you use the Microsoft API. I think there might be some helper code in the S3DM SDK that you may want to include.

You should keep all your platform dependent 3D mouse code in with your other platform dependent code (events, GUI, etc). The numbers you get should be the same though. Your view math should be able to be platform independent. Some axes will be swapped, but you can make those consistent in your platform dependent code.

[ngomes]

On Linux, a developer has the option to use libusb from a user-mode application.
There are issues with the solution (focus tracking, for example) but with a careful implementation and good testing, it should work just as well as with the 3Dconnexion SDK.

The 3Dconnexion SDK (ClientMessage -based implementation) is far easier to code for.

[szerbst]

Again, thanks for your comments. I was hoping to keep the platform dependent code to a minimum.

But if this is the recommended way I will start designing our integration for using raw input on Windows and the 3dconnexion SDK on Linux.

regards,
Stefan

[jwick]

It always requires some platform dependent code since nothing libusb, Raw Input, DirectInput, HID, etc. is available everywhere. Many years ago we had a proprietary API that hid much of that, but even then you still had to supply a Microsoft HWND instead of an X Window, to make up for the differences in the underlying platforms. The bottom line is that the platforms all expose events from devices differently, and will for the forseeable future.

[DaveLock]

I'm having a go at writing a C++ plug-in to add 3Dx functionality to an application that doesn't have it, but I think should (dusting off the C++ cobwebs, hehe). I'm not trying to write something that has high end appeal, but I want it to be functional, but before I code the 3Dx side I want to clarify something.

With reference to the comment quoted in this thread:

Using this method bypasses the 3DxWare driver, so nothing your users will do in that GUi will effect your application.

If we specifically want the 3DxWare GUI to not be bypassed, what method(s) out of the ones mentioned in the developers forum should we choose?

I understand that raw input might be a desirable low impact method from the viewpoint of the user not requiring to install a driver, but if that method means it bypasses the 3DxWare GUI, don't we then have to spend time to code in the features that are already in the GUI, such as flipping axes, speed etc. Please advise what method(s) use(s) the 3DxWare GUI settings for device control.

With my plug-in, I started down the path of coding the raw input method up to the point of registering the device successfully. What made me halt coding at that point & ponder if raw input was the best way to go is that when I open a commercial application that has inbuilt support for the 3Dx device, the 3DxWare GUI automatically knows the application & displays its name in the config dropdown. I assumed that registering with raw input for the device would do that too, but it doesn't (unless I've missed something).

So my other questions is, what exactly is it that makes the 3DxWare GUI know that "program XYZ" currently has the window focus?

Because my project is only a little plug-in, I want the GUI settings to be used & the GUI to know the application hosting the plug-in.

Thanks,

Dave.

[jwick]

Hi Dave,

We need more details before we can give you a recommendation.

For one, there is a version of the 3DxWare driver in beta now that works with Raw Input. Using this, you could still use the 3DxWare GUI to do common settings for your application. That does though mean that your application is no longer Plug'n'Play. The end user has to install 3DxWare. We'd prefer that you do some "simple" settings inside your program, as shown in the S3DM (Standard 3D Mouse) SDK. There is no reason to do everything the 3DxWare GUI does.

That still may not work in your situation. The driver looks at the window with focus and finds the underlying executable. That is the primary method used to determine which configuration to load.

How does your application run? Does it have a window that will get focus? Is it embedded into another executable, as a plugin, or run as a web page?

I think you can do everything with Raw Input that you could do with the old SDK.

Jim
3Dx Software Development

[DaveLock]

Thanks for the reply Jim.

... We need more details ... there is a version of the 3DxWare driver in beta now that works with Raw Input ... That does though mean that your application is no longer Plug'n'Play.

That doesn't bother me in the slightest. Having it plug & play was never a huge consideration for me really. I don't mind that the user has to install the 3DxWare driver for my plug-in to work. It's likely the users would have 3DxWare installed anyway IMO.

... We'd prefer that you do some "simple" settings inside your program, as shown in the S3DM (Standard 3D Mouse) SDK...

That would be a pain for me. If I were writing the application, I agree. But I'm just writing a plug-in that has to operate within the application's pre-existing classes & architecture. The dialog library is QT (a pain IMO). In fact, the thought of having to do a settings dialog myself would probably kill the project for me. The application's SDK comes with some plug-in examples that contain dialogs done in QT for it. Half of them won't build (for me), the others hang the application.

That still may not work in your situation. The driver looks at the window with focus and finds the underlying executable. That is the primary method used to determine which configuration to load.

Hmm. Do I understand then that it is the driver looking for compatible applications (using the window with focus), not the application window informing the driver that it is a compatible application?

If yes, how does the driver determine what is a compatible application? Does it have a list of applications it looks for? Where is that list?

For example, without me ever having created config settings for Acrobat (a 3Dx compatible application), how does the GUI know to load a config for it? Yet when I open Word (not a 3Dx compatible application), no config loads.

How does your application run? Does it have a window that will get focus? Is it embedded into another executable, as a plugin, or run as a web page?

The application that will load & run my plug-in is an exe file program that has 1 main window, which gets the focus. My plug-in is written in C++ using the application's SDK examples as guidance, is built, & placed into the application's plug-ins folder. The application either loads all the plug-ins in the plug-ins folder on start, or it hangs if any of the plug-ins make it unhappy. It is similar to the plug-in architecture of its sister applications Max, Maya, Motion Builder etc., as well as (as far as I know) most other mainstream software that has plug-in architecture open to 3rd parties.


Thanks again,

Dave.

[jwick]

It's likely the users would have 3DxWare installed anyway IMO.

This is likely for quite a while.

Half of them won't build (for me), the others hang the application.

...as all good sample code should

Hmm. Do I understand then that it is the driver looking for compatible applications (using the window with focus), not the application window informing the driver that it is a compatible application?

If yes, how does the driver determine what is a compatible application? Does it have a list of applications it looks for? Where is that list?

Preferably, you create a config file for your app to tell us what you want. Otherwise, we have an elaborate mechanism for trying to read your mind (AKA defaults).

For example, without me ever having created config settings for Acrobat (a 3Dx compatible application), how does the GUI know to load a config for it? Yet when I open Word (not a 3Dx compatible application), no config loads.

I think we deliver a config file for Acrobat. Otherwise, when it contacts the driver and we don't find a config file, we use the defaults.

Word never contacts the driver and there is no config file for it. We have nothing to fall back on, so we ignore it. In 3Dx7, we always try to do something. We don't ignore any applications.

The application that will load & run my plug-in is an exe file program that has 1 main window, which gets the focus. My plug-in is written in C++ using the application's SDK examples as guidance, is built, & placed into the application's plug-ins folder. The application either loads all the plug-ins in the plug-ins folder on start, or it hangs if any of the plug-ins make it unhappy. It is similar to the plug-in architecture of its sister applications Max, Maya, Motion Builder etc., as well as (as far as I know) most other mainstream software that has plug-in architecture open to 3rd parties.

This could be an issue. If the parent program also supports the 3D mouse, we may have a conflict finding you down there running as a plugin. I'd have to talk to some of the others to figure that out. What exactly is the parent program? PM me if you don't want to put it in here.

Jim

[DaveLock]

It's likely the users would have 3DxWare installed anyway IMO.

This is likely for quite a while.

Future versions of the application which I'm writing the plug-in for may have inbuilt 3Dx support, which negates the need to use my plug-in at all. I'm writing it for how the situation is now.

Preferably, you create a config file for your app to tell us what you want. Otherwise, we have an elaborate mechanism for trying to read your mind (AKA defaults).

Where does the config file live?

I think we deliver a config file for Acrobat. Otherwise, when it contacts the driver and we don't find a config file, we use the defaults.

Word never contacts the driver and there is no config file for it. We have nothing to fall back on, so we ignore it. In 3Dx7, we always try to do something. We don't ignore any applications.

So initially it's the application that is making contact with the driver?
That then brings me back to my original question. Is there a particular method of 3Dx device incorporation that makes contact with the driver because simply registering for raw input doesn't do it.

I'm still wondering which method(s) utilise(s) the GUI's settings. If raw input bypasses the GUI, which doesn't bypass it?

This could be an issue. If the parent program also supports the 3D mouse, we may have a conflict finding you down there running as a plugin. I'd have to talk to some of the others to figure that out. What exactly is the parent program? PM me if you don't want to put it in here.

Autodesk Mudbox, & it doesn't have 3D mouse support.

The code for raw input registration within my plug-in succeeds in registering, so from that I'm guessing it will work. That's as far as I got though on the 3D mouse side because first I wanted to find out more about the different 3Dx methods. I've got the camera movement functions sorted waiting to call them from processing the 3D mouse input.


Dave.

[jwick]

Hi Dave,

I recommend that you continue your development with Raw Input. If you need the driver GUI, we can let you use the beta. I want you to do the view mathematics with base Raw Input though. It prevents mistakes caused by accidentally having the driver doing something behind your back. It is best to do the development without 3DxWare installed.

Use the Raw Input code from the S3DM SDK. That will work with and without the 3DxWare driver running. There are some special fixes in there for bugs (?) in Raw Input.

Jim

[DaveLock]

Hi Jim,

First up thanks so much for all your replies. It's very much appreciated.

I recommend that you continue your development with Raw Input. If you need the driver GUI, we can let you use the beta. I want you to do the view mathematics with base Raw Input though. It prevents mistakes caused by accidentally having the driver doing something behind your back. It is best to do the development without 3DxWare installed.

Use the Raw Input code from the S3DM SDK. That will work with and without the 3DxWare driver running. There are some special fixes in there for bugs (?) in Raw Input.

I've been keeping an iron in both fires, so to speak, by so far developing this plug-in with both the raw input method & the TDxInput method. I have them separated out & test by initialising one or the other, so they're not both functional at the same time. I was thinking when I decide which is the best I'll just cull the code of the other one out of the cpp file.

With the raw input method:
I looked at the S3DM sample in the SDK (I even downloaded the latest SDK v2.0.1 r6379 last Friday), & I have to say it looks a little daunting to a dumbo like me. It doesn't build for me either, but neither did the previous version r5794 I had (likely something I'm not doing correctly). Your WM_INPUT example I downloaded (which builds like a dream ) from a link in the forum is much easier to follow.

Anyway, as previously posted, registering the app for raw input from the device shows as successful, but that is as far as I get. Other samples I find on the net suggest that a callback is needed for raw input, such as the "LRESULT CALLBACK WndProc()" that your WM_INPUT example has. But in the S3DM sample, not only is there no WndProc, there's no WM_INPUT at all (just an ON_WM_INPUT() defined & in BEGIN_MESSAGE_MAP()). So I don't understand how that works.

So leveraging from your WM_INPUT example, I don't get any WM_INPUT in my switch (message) {} within the WndProc() callback. That got me thinking about something you said in your last post to me. If I'm sending the Mudbox window handle to register for raw input, the Mudbox application may have its own WndProc() callback function, so is the raw input going to go there instead of to my WndProc() function? If yes, I'm thinking it may not be possible to get raw input at a plug-in level.

With the TDxInput method:
I downloaded your TDxInput Monitor example, & although I don't know C#, it is the best & neatest sample of all IMO. It nails exactly what I want to achieve, & very efficiently too. My struggle with it though is trying to convert the C# to C++ code - would you happen to have this example in C++ (please say yes )?

I altered the translation & rotation readouts to be a percentage, so I can feed that directly to the camera movement commands in Mudbox - job done.

But I did notice something curious about the Monitor readout values. I have been using the Programming for the 3D Mouse PDF (p28 - p31) in the SDK as my guide for the camera movement. But what is shown there as the "rule of thumb" conflicts with the Monitor app readout values (which are coming from the TDxInput driver). The PDF shows a Y-axis translation for camera zoom in & out, but if you have the GUI set for a Y-axis zoom direction (to match the PDF), then Y-axis translation gives a Z-axis value from the driver. It seems to me the GUI zoom direction reverses the correct mapping of the axis values as per the PDF, because for the driver to map the axis values as per the PDF, the zoom direction has to be opposite to the PDF.

So, if you would happen to have the Monitor example in C++ code, it would be much appreciated. Other than that, to continue with raw input I would need to figure out why I get zero callback & WM_INPUT.


Dave.