3 * Copyright 1998 Marcus Meissner
4 * Copyright 1998 Rob Riggs
5 * Copyright 2000-2002 TransGaming Technologies, Inc.
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
21 * Most thread locking is complete. There may be a few race
22 * conditions still lurking.
25 * Implement SetCooperativeLevel properly (need to address focus issues)
26 * Implement DirectSound3DBuffers (stubs in place)
27 * Use hardware 3D support if available
28 * Add critical section locking inside Release and AddRef methods
29 * Handle static buffers - put those in hardware, non-static not in hardware
30 * Hardware DuplicateSoundBuffer
31 * Proper volume calculation for 3d buffers
32 * Remove DS_HEL_FRAGS and use mixer fragment length for it
38 #define NONAMELESSSTRUCT
39 #define NONAMELESSUNION
48 #include "wine/debug.h"
64 #include "dsound_private.h"
66 WINE_DEFAULT_DEBUG_CHANNEL(dsound);
68 struct list DSOUND_renderers = LIST_INIT(DSOUND_renderers);
69 CRITICAL_SECTION DSOUND_renderers_lock;
70 static CRITICAL_SECTION_DEBUG DSOUND_renderers_lock_debug =
72 0, 0, &DSOUND_renderers_lock,
73 { &DSOUND_renderers_lock_debug.ProcessLocksList, &DSOUND_renderers_lock_debug.ProcessLocksList },
74 0, 0, { (DWORD_PTR)(__FILE__ ": DSOUND_renderers_lock") }
76 CRITICAL_SECTION DSOUND_renderers_lock = { &DSOUND_renderers_lock_debug, -1, 0, 0, 0, 0 };
78 struct list DSOUND_capturers = LIST_INIT(DSOUND_capturers);
79 CRITICAL_SECTION DSOUND_capturers_lock;
80 static CRITICAL_SECTION_DEBUG DSOUND_capturers_lock_debug =
82 0, 0, &DSOUND_capturers_lock,
83 { &DSOUND_capturers_lock_debug.ProcessLocksList, &DSOUND_capturers_lock_debug.ProcessLocksList },
84 0, 0, { (DWORD_PTR)(__FILE__ ": DSOUND_capturers_lock") }
86 CRITICAL_SECTION DSOUND_capturers_lock = { &DSOUND_capturers_lock_debug, -1, 0, 0, 0, 0 };
88 GUID DSOUND_renderer_guids[MAXWAVEDRIVERS];
89 GUID DSOUND_capture_guids[MAXWAVEDRIVERS];
91 WCHAR wine_vxd_drv[] = { 'w','i','n','e','m','m','.','v','x','d', 0 };
93 /* All default settings, you most likely don't want to touch these, see wiki on UsefulRegistryKeys */
94 int ds_hel_buflen = 32768 * 2;
95 int ds_snd_queue_max = 10;
96 static HINSTANCE instance;
99 * Get a config key from either the app-specific or the default config
102 static inline DWORD get_config_key( HKEY defkey, HKEY appkey, const char *name,
103 char *buffer, DWORD size )
105 if (appkey && !RegQueryValueExA( appkey, name, 0, NULL, (LPBYTE)buffer, &size )) return 0;
106 if (defkey && !RegQueryValueExA( defkey, name, 0, NULL, (LPBYTE)buffer, &size )) return 0;
107 return ERROR_FILE_NOT_FOUND;
112 * Setup the dsound options.
115 void setup_dsound_options(void)
117 char buffer[MAX_PATH+16];
118 HKEY hkey, appkey = 0;
121 buffer[MAX_PATH]='\0';
123 /* @@ Wine registry key: HKCU\Software\Wine\DirectSound */
124 if (RegOpenKeyA( HKEY_CURRENT_USER, "Software\\Wine\\DirectSound", &hkey )) hkey = 0;
126 len = GetModuleFileNameA( 0, buffer, MAX_PATH );
127 if (len && len < MAX_PATH)
130 /* @@ Wine registry key: HKCU\Software\Wine\AppDefaults\app.exe\DirectSound */
131 if (!RegOpenKeyA( HKEY_CURRENT_USER, "Software\\Wine\\AppDefaults", &tmpkey ))
133 char *p, *appname = buffer;
134 if ((p = strrchr( appname, '/' ))) appname = p + 1;
135 if ((p = strrchr( appname, '\\' ))) appname = p + 1;
136 strcat( appname, "\\DirectSound" );
137 TRACE("appname = [%s]\n", appname);
138 if (RegOpenKeyA( tmpkey, appname, &appkey )) appkey = 0;
139 RegCloseKey( tmpkey );
145 if (!get_config_key( hkey, appkey, "HelBuflen", buffer, MAX_PATH ))
146 ds_hel_buflen = atoi(buffer);
148 if (!get_config_key( hkey, appkey, "SndQueueMax", buffer, MAX_PATH ))
149 ds_snd_queue_max = atoi(buffer);
152 if (appkey) RegCloseKey( appkey );
153 if (hkey) RegCloseKey( hkey );
155 TRACE("ds_hel_buflen = %d\n", ds_hel_buflen);
156 TRACE("ds_snd_queue_max = %d\n", ds_snd_queue_max);
159 static const char * get_device_id(LPCGUID pGuid)
161 if (IsEqualGUID(&DSDEVID_DefaultPlayback, pGuid))
162 return "DSDEVID_DefaultPlayback";
163 else if (IsEqualGUID(&DSDEVID_DefaultVoicePlayback, pGuid))
164 return "DSDEVID_DefaultVoicePlayback";
165 else if (IsEqualGUID(&DSDEVID_DefaultCapture, pGuid))
166 return "DSDEVID_DefaultCapture";
167 else if (IsEqualGUID(&DSDEVID_DefaultVoiceCapture, pGuid))
168 return "DSDEVID_DefaultVoiceCapture";
169 return debugstr_guid(pGuid);
172 static HRESULT get_mmdevenum(IMMDeviceEnumerator **devenum)
176 init_hr = CoInitialize(NULL);
178 hr = CoCreateInstance(&CLSID_MMDeviceEnumerator, NULL,
179 CLSCTX_INPROC_SERVER, &IID_IMMDeviceEnumerator, (void**)devenum);
183 ERR("CoCreateInstance failed: %08x\n", hr);
190 static void release_mmdevenum(IMMDeviceEnumerator *devenum, HRESULT init_hr)
192 IMMDeviceEnumerator_Release(devenum);
193 if(SUCCEEDED(init_hr))
197 static HRESULT get_mmdevice_guid(IMMDevice *device, IPropertyStore *ps,
204 hr = IMMDevice_OpenPropertyStore(device, STGM_READ, &ps);
206 WARN("OpenPropertyStore failed: %08x\n", hr);
210 IPropertyStore_AddRef(ps);
212 PropVariantInit(&pv);
214 hr = IPropertyStore_GetValue(ps, &PKEY_AudioEndpoint_GUID, &pv);
216 IPropertyStore_Release(ps);
217 WARN("GetValue(GUID) failed: %08x\n", hr);
221 CLSIDFromString(pv.u.pwszVal, guid);
223 PropVariantClear(&pv);
224 IPropertyStore_Release(ps);
229 /***************************************************************************
230 * GetDeviceID [DSOUND.9]
232 * Retrieves unique identifier of default device specified
235 * pGuidSrc [I] Address of device GUID.
236 * pGuidDest [O] Address to receive unique device GUID.
240 * Failure: DSERR_INVALIDPARAM
243 * pGuidSrc is a valid device GUID or DSDEVID_DefaultPlayback,
244 * DSDEVID_DefaultCapture, DSDEVID_DefaultVoicePlayback, or
245 * DSDEVID_DefaultVoiceCapture.
246 * Returns pGuidSrc if pGuidSrc is a valid device or the device
247 * GUID for the specified constants.
249 HRESULT WINAPI GetDeviceID(LPCGUID pGuidSrc, LPGUID pGuidDest)
251 IMMDeviceEnumerator *devenum;
252 EDataFlow flow = (EDataFlow)-1;
253 ERole role = (ERole)-1;
256 TRACE("(%s,%p)\n", get_device_id(pGuidSrc),pGuidDest);
258 if(!pGuidSrc || !pGuidDest)
259 return DSERR_INVALIDPARAM;
261 init_hr = get_mmdevenum(&devenum);
265 if(IsEqualGUID(&DSDEVID_DefaultPlayback, pGuidSrc)){
268 }else if(IsEqualGUID(&DSDEVID_DefaultVoicePlayback, pGuidSrc)){
269 role = eCommunications;
271 }else if(IsEqualGUID(&DSDEVID_DefaultCapture, pGuidSrc)){
274 }else if(IsEqualGUID(&DSDEVID_DefaultVoiceCapture, pGuidSrc)){
275 role = eCommunications;
279 if(role != (ERole)-1 && flow != (EDataFlow)-1){
282 hr = IMMDeviceEnumerator_GetDefaultAudioEndpoint(devenum,
283 flow, role, &device);
285 WARN("GetDefaultAudioEndpoint failed: %08x\n", hr);
286 release_mmdevenum(devenum, init_hr);
287 return DSERR_NODRIVER;
290 hr = get_mmdevice_guid(device, NULL, pGuidDest);
291 IMMDevice_Release(device);
293 release_mmdevenum(devenum, init_hr);
295 return (hr == S_OK) ? DS_OK : hr;
298 release_mmdevenum(devenum, init_hr);
300 *pGuidDest = *pGuidSrc;
307 LPDSENUMCALLBACKA callA;
311 static BOOL CALLBACK a_to_w_callback(LPGUID guid, LPCWSTR descW, LPCWSTR modW, LPVOID data)
313 struct morecontext *context = data;
314 char descA[MAXPNAMELEN], modA[MAXPNAMELEN];
316 WideCharToMultiByte(CP_ACP, 0, descW, -1, descA, sizeof(descA), NULL, NULL);
317 WideCharToMultiByte(CP_ACP, 0, modW, -1, modA, sizeof(modA), NULL, NULL);
319 return context->callA(guid, descA, modA, context->data);
322 /***************************************************************************
323 * DirectSoundEnumerateA [DSOUND.2]
325 * Enumerate all DirectSound drivers installed in the system
328 * lpDSEnumCallback [I] Address of callback function.
329 * lpContext [I] Address of user defined context passed to callback function.
333 * Failure: DSERR_INVALIDPARAM
335 HRESULT WINAPI DirectSoundEnumerateA(
336 LPDSENUMCALLBACKA lpDSEnumCallback,
339 struct morecontext context;
341 if (lpDSEnumCallback == NULL) {
342 WARN("invalid parameter: lpDSEnumCallback == NULL\n");
343 return DSERR_INVALIDPARAM;
346 context.callA = lpDSEnumCallback;
347 context.data = lpContext;
349 return DirectSoundEnumerateW(a_to_w_callback, &context);
352 HRESULT get_mmdevice(EDataFlow flow, const GUID *tgt, IMMDevice **device)
354 IMMDeviceEnumerator *devenum;
355 IMMDeviceCollection *coll;
359 init_hr = get_mmdevenum(&devenum);
363 hr = IMMDeviceEnumerator_EnumAudioEndpoints(devenum, flow,
364 DEVICE_STATE_ACTIVE, &coll);
366 WARN("EnumAudioEndpoints failed: %08x\n", hr);
367 release_mmdevenum(devenum, init_hr);
371 hr = IMMDeviceCollection_GetCount(coll, &count);
373 IMMDeviceCollection_Release(coll);
374 release_mmdevenum(devenum, init_hr);
375 WARN("GetCount failed: %08x\n", hr);
379 for(i = 0; i < count; ++i){
382 hr = IMMDeviceCollection_Item(coll, i, device);
386 hr = get_mmdevice_guid(*device, NULL, &guid);
388 IMMDevice_Release(*device);
392 if(IsEqualGUID(&guid, tgt)){
393 IMMDeviceCollection_Release(coll);
394 release_mmdevenum(devenum, init_hr);
398 IMMDevice_Release(*device);
401 WARN("No device with GUID %s found!\n", wine_dbgstr_guid(tgt));
403 IMMDeviceCollection_Release(coll);
404 release_mmdevenum(devenum, init_hr);
406 return DSERR_INVALIDPARAM;
409 static BOOL send_device(IMMDevice *device, GUID *guid,
410 LPDSENUMCALLBACKW cb, void *user)
417 PropVariantInit(&pv);
419 hr = IMMDevice_OpenPropertyStore(device, STGM_READ, &ps);
421 WARN("OpenPropertyStore failed: %08x\n", hr);
425 hr = get_mmdevice_guid(device, ps, guid);
427 IPropertyStore_Release(ps);
431 hr = IPropertyStore_GetValue(ps,
432 (const PROPERTYKEY *)&DEVPKEY_Device_FriendlyName, &pv);
434 IPropertyStore_Release(ps);
435 WARN("GetValue(FriendlyName) failed: %08x\n", hr);
439 TRACE("Calling back with %s (%s)\n", wine_dbgstr_guid(guid),
440 wine_dbgstr_w(pv.u.pwszVal));
442 keep_going = cb(guid, pv.u.pwszVal, wine_vxd_drv, user);
444 PropVariantClear(&pv);
445 IPropertyStore_Release(ps);
450 /* S_FALSE means the callback returned FALSE at some point
451 * S_OK means the callback always returned TRUE */
452 HRESULT enumerate_mmdevices(EDataFlow flow, GUID *guids,
453 LPDSENUMCALLBACKW cb, void *user)
455 IMMDeviceEnumerator *devenum;
456 IMMDeviceCollection *coll;
457 IMMDevice *defdev = NULL;
462 static const WCHAR primary_desc[] = {'P','r','i','m','a','r','y',' ',
463 'S','o','u','n','d',' ','D','r','i','v','e','r',0};
464 static const WCHAR empty_drv[] = {0};
466 init_hr = get_mmdevenum(&devenum);
470 hr = IMMDeviceEnumerator_EnumAudioEndpoints(devenum, flow,
471 DEVICE_STATE_ACTIVE, &coll);
473 release_mmdevenum(devenum, init_hr);
474 WARN("EnumAudioEndpoints failed: %08x\n", hr);
478 hr = IMMDeviceCollection_GetCount(coll, &count);
480 IMMDeviceCollection_Release(coll);
481 release_mmdevenum(devenum, init_hr);
482 WARN("GetCount failed: %08x\n", hr);
487 release_mmdevenum(devenum, init_hr);
491 TRACE("Calling back with NULL (%s)\n", wine_dbgstr_w(primary_desc));
492 keep_going = cb(NULL, primary_desc, empty_drv, user);
494 /* always send the default device first */
496 hr = IMMDeviceEnumerator_GetDefaultAudioEndpoint(devenum, flow,
497 eMultimedia, &defdev);
502 keep_going = send_device(defdev, &guids[0], cb, user);
507 for(i = 0; keep_going && i < count; ++i){
510 hr = IMMDeviceCollection_Item(coll, i, &device);
512 WARN("Item failed: %08x\n", hr);
516 if(device != defdev){
517 send_device(device, &guids[n], cb, user);
521 IMMDevice_Release(device);
525 IMMDevice_Release(defdev);
526 IMMDeviceCollection_Release(coll);
528 release_mmdevenum(devenum, init_hr);
530 return (keep_going == TRUE) ? S_OK : S_FALSE;
533 /***************************************************************************
534 * DirectSoundEnumerateW [DSOUND.3]
536 * Enumerate all DirectSound drivers installed in the system
539 * lpDSEnumCallback [I] Address of callback function.
540 * lpContext [I] Address of user defined context passed to callback function.
544 * Failure: DSERR_INVALIDPARAM
546 HRESULT WINAPI DirectSoundEnumerateW(
547 LPDSENUMCALLBACKW lpDSEnumCallback,
552 TRACE("(%p,%p)\n", lpDSEnumCallback, lpContext);
554 if (lpDSEnumCallback == NULL) {
555 WARN("invalid parameter: lpDSEnumCallback == NULL\n");
556 return DSERR_INVALIDPARAM;
559 setup_dsound_options();
561 hr = enumerate_mmdevices(eRender, DSOUND_renderer_guids,
562 lpDSEnumCallback, lpContext);
563 return SUCCEEDED(hr) ? DS_OK : hr;
566 /***************************************************************************
567 * DirectSoundCaptureEnumerateA [DSOUND.7]
569 * Enumerate all DirectSound drivers installed in the system.
572 * lpDSEnumCallback [I] Address of callback function.
573 * lpContext [I] Address of user defined context passed to callback function.
577 * Failure: DSERR_INVALIDPARAM
579 HRESULT WINAPI DirectSoundCaptureEnumerateA(
580 LPDSENUMCALLBACKA lpDSEnumCallback,
583 struct morecontext context;
585 if (lpDSEnumCallback == NULL) {
586 WARN("invalid parameter: lpDSEnumCallback == NULL\n");
587 return DSERR_INVALIDPARAM;
590 context.callA = lpDSEnumCallback;
591 context.data = lpContext;
593 return DirectSoundCaptureEnumerateW(a_to_w_callback, &context);
596 /***************************************************************************
597 * DirectSoundCaptureEnumerateW [DSOUND.8]
599 * Enumerate all DirectSound drivers installed in the system.
602 * lpDSEnumCallback [I] Address of callback function.
603 * lpContext [I] Address of user defined context passed to callback function.
607 * Failure: DSERR_INVALIDPARAM
610 DirectSoundCaptureEnumerateW(
611 LPDSENUMCALLBACKW lpDSEnumCallback,
616 TRACE("(%p,%p)\n", lpDSEnumCallback, lpContext );
618 if (lpDSEnumCallback == NULL) {
619 WARN("invalid parameter: lpDSEnumCallback == NULL\n");
620 return DSERR_INVALIDPARAM;
623 setup_dsound_options();
625 hr = enumerate_mmdevices(eCapture, DSOUND_capture_guids,
626 lpDSEnumCallback, lpContext);
627 return SUCCEEDED(hr) ? DS_OK : hr;
630 /*******************************************************************************
631 * DirectSound ClassFactory
634 typedef HRESULT (*FnCreateInstance)(REFIID riid, LPVOID *ppobj);
637 IClassFactory IClassFactory_iface;
639 FnCreateInstance pfnCreateInstance;
642 static inline IClassFactoryImpl *impl_from_IClassFactory(IClassFactory *iface)
644 return CONTAINING_RECORD(iface, IClassFactoryImpl, IClassFactory_iface);
647 static HRESULT WINAPI
648 DSCF_QueryInterface(IClassFactory *iface, REFIID riid, LPVOID *ppobj)
650 IClassFactoryImpl *This = impl_from_IClassFactory(iface);
651 TRACE("(%p, %s, %p)\n", This, debugstr_guid(riid), ppobj);
654 if (IsEqualIID(riid, &IID_IUnknown) ||
655 IsEqualIID(riid, &IID_IClassFactory))
658 IClassFactory_AddRef(iface);
662 return E_NOINTERFACE;
665 static ULONG WINAPI DSCF_AddRef(LPCLASSFACTORY iface)
670 static ULONG WINAPI DSCF_Release(LPCLASSFACTORY iface)
672 /* static class, won't be freed */
676 static HRESULT WINAPI DSCF_CreateInstance(
677 LPCLASSFACTORY iface,
682 IClassFactoryImpl *This = impl_from_IClassFactory(iface);
683 TRACE("(%p, %p, %s, %p)\n", This, pOuter, debugstr_guid(riid), ppobj);
686 return CLASS_E_NOAGGREGATION;
689 WARN("invalid parameter\n");
690 return DSERR_INVALIDPARAM;
693 return This->pfnCreateInstance(riid, ppobj);
696 static HRESULT WINAPI DSCF_LockServer(LPCLASSFACTORY iface, BOOL dolock)
698 IClassFactoryImpl *This = impl_from_IClassFactory(iface);
699 FIXME("(%p, %d) stub!\n", This, dolock);
703 static const IClassFactoryVtbl DSCF_Vtbl = {
711 static IClassFactoryImpl DSOUND_CF[] = {
712 { { &DSCF_Vtbl }, &CLSID_DirectSound, DSOUND_Create },
713 { { &DSCF_Vtbl }, &CLSID_DirectSound8, DSOUND_Create8 },
714 { { &DSCF_Vtbl }, &CLSID_DirectSoundCapture, DSOUND_CaptureCreate },
715 { { &DSCF_Vtbl }, &CLSID_DirectSoundCapture8, DSOUND_CaptureCreate8 },
716 { { &DSCF_Vtbl }, &CLSID_DirectSoundFullDuplex, DSOUND_FullDuplexCreate },
717 { { &DSCF_Vtbl }, &CLSID_DirectSoundPrivate, IKsPrivatePropertySetImpl_Create },
718 { { NULL }, NULL, NULL }
721 /*******************************************************************************
722 * DllGetClassObject [DSOUND.@]
723 * Retrieves class object from a DLL object
726 * Docs say returns STDAPI
729 * rclsid [I] CLSID for the class object
730 * riid [I] Reference to identifier of interface for class object
731 * ppv [O] Address of variable to receive interface pointer for riid
735 * Failure: CLASS_E_CLASSNOTAVAILABLE, E_OUTOFMEMORY, E_INVALIDARG,
738 HRESULT WINAPI DllGetClassObject(REFCLSID rclsid, REFIID riid, LPVOID *ppv)
741 TRACE("(%s, %s, %p)\n", debugstr_guid(rclsid), debugstr_guid(riid), ppv);
744 WARN("invalid parameter\n");
750 if (!IsEqualIID(riid, &IID_IClassFactory) &&
751 !IsEqualIID(riid, &IID_IUnknown)) {
752 WARN("no interface for %s\n", debugstr_guid(riid));
753 return E_NOINTERFACE;
756 while (NULL != DSOUND_CF[i].rclsid) {
757 if (IsEqualGUID(rclsid, DSOUND_CF[i].rclsid)) {
758 DSCF_AddRef(&DSOUND_CF[i].IClassFactory_iface);
759 *ppv = &DSOUND_CF[i];
765 WARN("(%s, %s, %p): no class found.\n", debugstr_guid(rclsid),
766 debugstr_guid(riid), ppv);
767 return CLASS_E_CLASSNOTAVAILABLE;
771 /*******************************************************************************
772 * DllCanUnloadNow [DSOUND.4]
773 * Determines whether the DLL is in use.
776 * Can unload now: S_OK
777 * Cannot unload now (the DLL is still active): S_FALSE
779 HRESULT WINAPI DllCanUnloadNow(void)
784 #define INIT_GUID(guid, l, w1, w2, b1, b2, b3, b4, b5, b6, b7, b8) \
785 guid.Data1 = l; guid.Data2 = w1; guid.Data3 = w2; \
786 guid.Data4[0] = b1; guid.Data4[1] = b2; guid.Data4[2] = b3; \
787 guid.Data4[3] = b4; guid.Data4[4] = b5; guid.Data4[5] = b6; \
788 guid.Data4[6] = b7; guid.Data4[7] = b8;
790 /***********************************************************************
791 * DllMain (DSOUND.init)
793 BOOL WINAPI DllMain(HINSTANCE hInstDLL, DWORD fdwReason, LPVOID lpvReserved)
795 TRACE("(%p %d %p)\n", hInstDLL, fdwReason, lpvReserved);
798 case DLL_PROCESS_ATTACH:
799 TRACE("DLL_PROCESS_ATTACH\n");
801 DisableThreadLibraryCalls(hInstDLL);
802 /* Increase refcount on dsound by 1 */
803 GetModuleHandleExW(GET_MODULE_HANDLE_EX_FLAG_FROM_ADDRESS, (LPCWSTR)hInstDLL, &hInstDLL);
805 case DLL_PROCESS_DETACH:
806 TRACE("DLL_PROCESS_DETACH\n");
807 DeleteCriticalSection(&DSOUND_renderers_lock);
808 DeleteCriticalSection(&DSOUND_capturers_lock);
811 TRACE("UNKNOWN REASON\n");
817 /***********************************************************************
818 * DllRegisterServer (DSOUND.@)
820 HRESULT WINAPI DllRegisterServer(void)
822 return __wine_register_resources( instance );
825 /***********************************************************************
826 * DllUnregisterServer (DSOUND.@)
828 HRESULT WINAPI DllUnregisterServer(void)
830 return __wine_unregister_resources( instance );