Blender V5.3
GHOST_NDOFManagerCocoa.mm
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2010-2023 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
6
8#import <Cocoa/Cocoa.h>
9
10#include <cstdint>
11#include <dlfcn.h>
12
13#define DEBUG_NDOF_DRIVER false
14
15#if DEBUG_NDOF_DRIVER
16# include <cstdio>
17#endif
18
19/* Static callback functions need to talk to these objects: */
22
23static uint16_t clientID = 0;
24
25static bool driver_loaded = false;
26
27/* 3DxMacCore version >= minimal_version is considered "new".
28 * It was firstly introduced in 3DxWare v10.8.4 r3716 and can process
29 * (not yet documented in SDK manual) kConnexionCmdAppEvent events. */
30static NSString *new_driver_minimal_version = @"1.3.4.473";
31
32/* Replicate just enough of the 3Dx API for our uses, not everything the driver provides. */
33
34#define kConnexionClientModeTakeOver 1
35#define kConnexionMaskAll 0x3fff
36#define kConnexionMaskAxis 0x3f00
37#define kConnexionMaskNoButtons 0x0
38#define kConnexionMaskAllButtons 0xffffffff
39#define kConnexionCmdHandleButtons 2
40#define kConnexionCmdHandleAxis 3
41#define kConnexionCmdAppSpecific 10
42#define kConnexionCmdAppEvent 11
43#define kConnexionMsgDeviceState '3dSR'
44#define kConnexionCtlGetDeviceID '3did'
45
46#pragma pack(push, 2) /* Just this struct. */
48 uint16_t version;
49 uint16_t client;
50 uint16_t command;
51 int16_t param;
54 uint8_t report[8];
56 int16_t axis[6]; /* TX, TY, TZ, RX, RY, RZ. */
57 uint16_t address;
58 uint32_t buttons;
59};
60#pragma pack(pop)
61
62/* Callback functions: */
63typedef void (*AddedHandler)(uint32_t);
64typedef void (*RemovedHandler)(uint32_t);
65typedef void (*MessageHandler)(uint32_t, uint32_t msg_type, void *msg_arg);
66
67/* Driver functions: */
70typedef uint16_t (*RegisterConnexionClient_ptr)(uint32_t signature,
71 const char *name,
72 uint16_t mode,
73 uint32_t mask);
74typedef void (*SetConnexionClientButtonMask_ptr)(uint16_t clientID, uint32_t buttonMask);
75typedef void (*UnregisterConnexionClient_ptr)(uint16_t clientID);
76typedef int16_t (*ConnexionClientControl_ptr)(uint16_t clientID,
77 uint32_t message,
78 int32_t param,
79 int32_t *result);
80
81#define DECLARE_FUNC(name) name##_ptr name = nullptr
82
83DECLARE_FUNC(SetConnexionHandlers);
84DECLARE_FUNC(CleanupConnexionHandlers);
85DECLARE_FUNC(RegisterConnexionClient);
86DECLARE_FUNC(SetConnexionClientButtonMask);
87DECLARE_FUNC(UnregisterConnexionClient);
88DECLARE_FUNC(ConnexionClientControl);
89
90static void *load_func(void *module, const char *func_name)
91{
92 void *func = dlsym(module, func_name);
93
94#if DEBUG_NDOF_DRIVER
95 if (func) {
96 printf("'%s' loaded :D\n", func_name);
97 }
98 else {
99 printf("<!> %s\n", dlerror());
100 }
101#endif
102
103 return func;
104}
105
106#define LOAD_FUNC(name) name = (name##_ptr)load_func(module, #name)
107
108static void *module; /* Handle to the whole driver. */
109
111{
112 if (driver_loaded) {
113 return true;
114 }
115
116 module = dlopen("/Library/Frameworks/3DconnexionClient.framework/3DconnexionClient",
117 RTLD_LAZY | RTLD_LOCAL);
118
119 if (module) {
120 LOAD_FUNC(SetConnexionHandlers);
121
122 if (SetConnexionHandlers != nullptr) {
123 driver_loaded = true;
124 }
125
126 if (driver_loaded) {
127 LOAD_FUNC(CleanupConnexionHandlers);
128 LOAD_FUNC(RegisterConnexionClient);
129 LOAD_FUNC(SetConnexionClientButtonMask);
130 LOAD_FUNC(UnregisterConnexionClient);
131 LOAD_FUNC(ConnexionClientControl);
132 }
133 }
134#if DEBUG_NDOF_DRIVER
135 else {
136 printf("<!> %s\n", dlerror());
137 }
138
139 printf("loaded: %s\n", driver_loaded ? "YES" : "NO");
140#endif
141
142 return driver_loaded;
143}
144
145static void unload_driver()
146{
147 dlclose(module);
148}
149
150static void DeviceAdded(uint32_t /*unused*/)
151{
152#if DEBUG_NDOF_DRIVER
153 printf("ndof: device added\n");
154#endif
155
156 /* Determine exactly which device is plugged in. */
157 int32_t result;
158 ConnexionClientControl(clientID, kConnexionCtlGetDeviceID, 0, &result);
159 const int16_t vendorID = result >> 16;
160 const int16_t productID = result & 0xffff;
161
162 ndof_manager->setDevice(vendorID, productID);
163}
164
165static void DeviceRemoved(uint32_t /*unused*/)
166{
167#if DEBUG_NDOF_DRIVER
168 printf("ndof: device removed\n");
169#endif
170}
171
172static void DeviceEvent(uint32_t /*unused*/, uint32_t msg_type, void *msg_arg)
173{
174 if (msg_type == kConnexionMsgDeviceState) {
176
177 /* Device state is broadcast to all clients; only react if sent to us. */
178 if (s->client == clientID) {
179 /* TODO: is s->time compatible with GHOST timestamps? if so use that instead. */
181
182 switch (s->command) {
184 /* convert to blender view coordinates. */
185 const int t[3] = {s->axis[0], -(s->axis[2]), s->axis[1]};
186 const int r[3] = {-(s->axis[3]), s->axis[5], -(s->axis[4])};
187
190
192 break;
193 }
195 const int button_bits = s->buttons;
196#ifdef DEBUG_NDOF_BUTTONS
197 printf("button bits: 0x%08x\n", button_bits);
198#endif
199 ndof_manager->updateButtonsBitmask(button_bits, now);
201 break;
202 }
204 const int button_number = s->value;
205 const bool pressed = s->appEventPressed;
206#ifdef DEBUG_NDOF_BUTTONS
207 printf("button number: %d, pressed: %d\n", button_number, pressed);
208#endif
209 ndof_manager->updateButton(GHOST_NDOF_ButtonT(button_number), pressed, now);
211 break;
212 }
213#if DEBUG_NDOF_DRIVER
215 printf("ndof: app-specific command, param = %hd, value = %d\n", s->param, s->value);
216 break;
217
218 default:
219 printf("ndof: mystery device command %d\n", s->command);
220#endif
221 }
222 }
223 }
224}
225
227{
228 if (load_driver_functions()) {
229 /* Give static functions something to talk to: */
230 ghost_system = dynamic_cast<GHOST_SystemCocoa *>(&sys);
231 ndof_manager = this;
232
233 const uint16_t error = SetConnexionHandlers(DeviceEvent, DeviceAdded, DeviceRemoved, true);
234
235 if (error) {
236#if DEBUG_NDOF_DRIVER
237 printf("ndof: error %d while setting up handlers\n", error);
238#endif
239 return;
240 }
241
242 const NSDictionary *dictInfos =
243 [NSBundle bundleWithPath:@"/Library/Frameworks/3DconnexionClient.framework"]
244 .infoDictionary;
245 NSString *strVersion = [dictInfos objectForKey:(NSString *)kCFBundleVersionKey];
246 const auto compare = [strVersion compare:new_driver_minimal_version];
247 const bool has_new_driver = compare != NSOrderedAscending;
248
249 /* New driver makes use of kConnexionCmdAppEvent events, which require to have all buttons
250 * unmasked. Basically, this means that driver consumes all NDOF device input and then sends
251 * appropriate app events based on its configuration instead of forwarding raw data to the
252 * application. When using an older driver, the old solution with all buttons forwarded
253 * (masked) is preferred. */
254 const uint32_t client_mask = has_new_driver ? kConnexionMaskAxis : kConnexionMaskAll;
255 const uint32_t button_mask = has_new_driver ? kConnexionMaskNoButtons :
257
258 /* Pascal string *and* a four-letter constant. How old-school. */
259 clientID = RegisterConnexionClient(
260 'blnd', "\007blender", kConnexionClientModeTakeOver, client_mask);
261
262 SetConnexionClientButtonMask(clientID, button_mask);
263 }
264}
265
267{
268 if (driver_loaded) {
269 UnregisterConnexionClient(clientID);
270 CleanupConnexionHandlers();
272
273 ghost_system = nullptr;
274 ndof_manager = nullptr;
275 }
276}
277
static void DeviceAdded(uint32_t)
static GHOST_NDOFManager * ndof_manager
static void DeviceRemoved(uint32_t)
void(*) RemovedHandler(uint32_t)
#define kConnexionMaskNoButtons
#define kConnexionCmdAppSpecific
void(*) UnregisterConnexionClient_ptr(uint16_t clientID)
#define kConnexionCmdAppEvent
#define kConnexionCmdHandleButtons
static bool load_driver_functions()
static void unload_driver()
#define kConnexionMaskAxis
void(*) CleanupConnexionHandlers_ptr()
static NSString * new_driver_minimal_version
static uint16_t clientID
uint16_t(*) RegisterConnexionClient_ptr(uint32_t signature, const char *name, uint16_t mode, uint32_t mask)
void(*) AddedHandler(uint32_t)
static bool driver_loaded
void(*) MessageHandler(uint32_t, uint32_t msg_type, void *msg_arg)
#define DECLARE_FUNC(name)
#define kConnexionMsgDeviceState
int16_t(*) ConnexionClientControl_ptr(uint16_t clientID, uint32_t message, int32_t param, int32_t *result)
#define kConnexionMaskAll
#define kConnexionCtlGetDeviceID
#define kConnexionCmdHandleAxis
int16_t(*) SetConnexionHandlers_ptr(MessageHandler, AddedHandler, RemovedHandler, bool)
void(*) SetConnexionClientButtonMask_ptr(uint16_t clientID, uint32_t buttonMask)
static void * load_func(void *module, const char *func_name)
#define kConnexionMaskAllButtons
static void DeviceEvent(uint32_t, uint32_t msg_type, void *msg_arg)
#define kConnexionClientModeTakeOver
#define LOAD_FUNC(name)
static GHOST_SystemCocoa * ghost_system
GHOST_NDOF_ButtonT
unsigned long long int uint64_t
void updateButtonsBitmask(int button_bits, uint64_t time)
void updateButton(GHOST_NDOF_ButtonT button, bool press, uint64_t time)
void updateTranslation(const int t[3], uint64_t time)
GHOST_NDOFManager(GHOST_System &)
void updateRotation(const int r[3], uint64_t time)
bool setDevice(unsigned short vendor_id, unsigned short product_id)
uint64_t getMilliSeconds() const override
#define printf
ccl_device_inline float2 mask(const MaskType mask, const float2 a)
static struct PyModuleDef module
Definition python.cpp:944