Windows uygulamalarında XInput'u Kullanmaya Başlama

XInput, Windows uygulamalarının denetleyici etkileşimlerini işlemesine olanak tanır (denetleyici çakışması efektleri ve ses girişi ve çıkışı dahil).

Bu konu, XInput'un özelliklerine ve uygulamada nasıl ayarlanacağına ilişkin kısa bir genel bakış sağlar. Aşağıdakileri içerir:

XInput'a giriş

Uygulamalar, Bir Windows bilgisayara takılıyken oyun denetleyicileriyle iletişim kurmak için XInput API'sini kullanabilir (aynı anda en fazla dört benzersiz denetleyici takılabilir).

Bu API kullanılarak, uyumlu herhangi bir bağlı denetleyici durumunu sorgulayabilir ve titreşim efektleri ayarlanabilir. Mikrofonlu kulaklığın takılı olduğu denetleyiciler, ses işleme için kulaklıkla birlikte kullanılabilen ses girişi ve çıkış cihazları için de sorgulanabilir.

Denetleyici Düzeni

Uyumlu denetleyicilerin her biri dijital düğmeli iki analog yön çubuğu, iki analog tetikleyicisi, dört yönü olan dijital yön paneli ve sekiz dijital düğmesi vardır. XInputGetState işlevi çağrıldığında bu girişlerin her birinin durumları XINPUT_GAMEPAD yapısında döndürülür.

Denetleyici ayrıca kullanıcıya zorla geri bildirim efektleri sağlamak için iki titreşim motoruna sahiptir. Bu motorların hızları, titreşim etkilerini ayarlamak için XInputSetState işlevine geçirilen XINPUT_VIBRATION yapısında belirtilir.

İsteğe bağlı olarak, kumandaya bir kulaklık bağlanabilir. Mikrofonlu kulaklıkta ses girişi için bir mikrofon ve ses çıkışı için bir kulaklık bulunur. Mikrofon ve kulaklık cihazlarına karşılık gelen cihaz tanımlayıcılarını almak için XInputGetAudioDeviceIds veya eski XInputGetDSoundAudioDeviceGuids işlevini çağırabilirsiniz. Ardından ses girişi almak ve ses çıkışı göndermek için Core Audio API'lerini kullanabilirsiniz.

XInput kullanma

XInput kullanmak, XInput işlevlerini gerektiği kadar çağırmak kadar basittir. XInput işlevlerini kullanarak denetleyici durumunu alabilir, kulaklık ses kimliklerini alabilir ve denetleyici titreşim efektlerini ayarlayabilirsiniz.

Birden Çok Denetleyici

XInput API'si her zaman en fazla dört denetleyiciyi destekler. XInput işlevlerinin tümü, ayarlanan veya sorgulanan denetleyiciyi tanımlamak için geçirilen bir dwUserIndex parametresi gerektirir. Bu kimlik 0-3 aralığında olur ve XInput tarafından otomatik olarak ayarlanır. Sayı, denetleyicinin takılı olduğu bağlantı noktasına karşılık gelir ve değiştirilemez.

Her denetleyici, kumandanın ortasındaki "ışık halkası" üzerinde bir çeyrek ışık yakarak hangi kimliği kullandığını görüntüler. 0 dwUserIndex değeri sol üst kadrana karşılık gelir; numaralandırma halkanın etrafında saat yönünde ilerler.

Uygulamalar birden çok denetleyiciyi desteklemelidir.

Denetleyici Durumunu Alma

Uygulama süresi boyunca, bir denetleyiciden durum alma büyük olasılıkla en sık yapılır. Bir oyun uygulamasında kareden kareye durum alınmalıdır ve oyun bilgileri denetleyici değişikliklerini yansıtacak şekilde güncelleştirilmelidir.

Durumu almak için XInputGetState işlevini kullanın:

DWORD dwResult;    
for (DWORD i=0; i< XUSER_MAX_COUNT; i++ )
{
    XINPUT_STATE state;
    ZeroMemory( &state, sizeof(XINPUT_STATE) );

    // Simply get the state of the controller from XInput.
    dwResult = XInputGetState( i, &state );

    if( dwResult == ERROR_SUCCESS )
    {
        // Controller is connected
    }
    else
    {
        // Controller is not connected
    }
}

denetleyicinin bağlı olup olmadığını belirlemek için XInputGetState dönüş değerinin kullanılabileceğini unutmayın. Uygulamalar iç denetleyici bilgilerini barındıracak bir yapı tanımlamalıdır; bu bilgiler, düğme basışları veya analog denetleyici deltaları gibi hangi değişikliklerin bu çerçevede yapıldığını belirlemek için XInputGetState sonuçlarıyla karşılaştırılmalıdır. Yukarıdaki örnekte, g_Controllers böyle bir yapıyı temsil eder.

Durum bir XINPUT_STATE yapısında alındıktan sonra, değişiklikleri kontrol edebilir ve kontrolcü durumu hakkında spesifik bilgiler alabilirsiniz.

XINPUT_STATE yapısının dwPacketNumber üyesi, XInputGetStateson çağrıdan sonra denetleyici durumunun değişip değişmediğini denetlemek için kullanılabilir. dwPacketNumberXInputGetStateardışık iki çağrı arasında değişmezse, durumda hiçbir değişiklik yoktur. Farklıysa, uygulama daha ayrıntılı durum bilgileri almak için XINPUT_STATE yapısının Gamepad üyesini denetlemelidir.

Performans nedenleriyle, her karede 'boş' bir kullanıcı yuvası için XInputGetState çağırmayın. Bunun yerine, yeni denetleyicilerin denetimlerini birkaç saniyede bir aralıklarla ayırmanızı öneririz.

Ölü Bölge

Kullanıcıların tutarlı bir oyun deneyimi yaşamaları için, oyununuzun ölü bölgeyi doğru bir şekilde uygulaması gerekir. Ölü bölge, analog parmak çubuklarına dokunulmadığında ve ortalandığında bile denetleyici tarafından bildirilen "hareket" değerleridir. Ayrıca 2 analog tetikleyici için bir ölü bölge vardır.

Dikkat

Hiç ölü bölgeyi filtrelemeyen XInput kullanan oyunlar kötü bir oyun deneyimi yaşar. Bazı denetleyicilerin diğerlerinden daha hassas olduğunu, bu nedenle ölü bölgenin birimden birime değişebileceğini lütfen unutmayın. Oyunlarınızı farklı sistemlerde birkaç farklı oyun kumandasıyla test edin.

Uygulamalar, çubukta veya tetikleyicide geçerli sayılacak kadar bir hareketin ne zaman yapıldığını belirtmek için analog girişlerde (tetikleyiciler, çubuklar) "ölü bölgeler" kullanmalıdır.

Uygulamanız, aşağıdaki örnekte olduğu gibi ölü bölgeleri denetlemeli ve uygun şekilde yanıt vermelidir:

XINPUT_STATE state = g_Controllers[i].state;

float LX = state.Gamepad.sThumbLX;
float LY = state.Gamepad.sThumbLY;

//determine how far the controller is pushed
float magnitude = sqrt(LX*LX + LY*LY);

//determine the direction the controller is pushed
float normalizedLX = LX / magnitude;
float normalizedLY = LY / magnitude;

float normalizedMagnitude = 0;

//check if the controller is outside a circular dead zone
if (magnitude > INPUT_DEADZONE)
{
    //clip the magnitude at its expected maximum value
    if (magnitude > 32767) magnitude = 32767;

    //adjust magnitude relative to the end of the dead zone
    magnitude -= INPUT_DEADZONE;

    //optionally normalize the magnitude with respect to its expected range
    //giving a magnitude value of 0.0 to 1.0
    normalizedMagnitude = magnitude / (32767 - INPUT_DEADZONE);
}
else //if the controller is in the deadzone zero out the magnitude
{
    magnitude = 0.0;
    normalizedMagnitude = 0.0;
}

//repeat for right thumb stick

Bu örnek, denetleyicinin yön vektörunu ve denetleyicinin ne kadar uzağa gönderildiğini hesaplar. Bu, denetleyicinin büyüklüğünün ölü bölge değerinden büyük olup olmadığını denetleyerek dairesel bir ölü bölge uygulanmasına olanak tanır. Buna ek olarak kod oyun kumandasının büyüklüğünü normalleştirir ve oyun kumandasının konumunu oyuna özgü birimlere dönüştürmek için oyuna özgü bir faktörle çarpılabilir.

Çubuklar ve tetikleyiciler için kendi ölü bölgelerinizi tanımlayabilirsiniz (0-65534 arasında) veya XInput.h'de XINPUT_GAMEPAD_LEFT_THUMB_DEADZONE, XINPUT_GAMEPAD_RIGHT_THUMB_DEADZONE ve XINPUT_GAMEPAD_TRIGGER_THRESHOLD olarak tanımlanan sağlanan ölü bölgeleri kullanabilirsiniz:

#define XINPUT_GAMEPAD_LEFT_THUMB_DEADZONE  7849
#define XINPUT_GAMEPAD_RIGHT_THUMB_DEADZONE 8689
#define XINPUT_GAMEPAD_TRIGGER_THRESHOLD    30

Ölü bölge zorunlu kılındıktan sonra elde edilen [0.0..1.0] kayan noktayı (yukarıdaki örnekte olduğu gibi) ölçeklendirmeyi ve isteğe bağlı olarak doğrusal olmayan bir dönüşüm uygulamayı yararlı bulabilirsiniz.

Örneğin, sürüş oyunlarında, sonucun bir gamepad kullanarak araba sürme konusunda daha iyi bir his sağlamak için küp oluşturması yararlı olabilir, çünkü sonuç daha düşük aralıklarda size daha fazla hassasiyet verir, bu arzu edilir, çünkü oyuncular genellikle hafif bir hareket elde etmek için yumuşak kuvvet uygular veya rd yanıtı almak için tek yönde sert kuvvet uygular.

Titreşim Efektlerini Ayarlama

Denetleyicinin durumunu almaya ek olarak, denetleyicinin kullanıcısına sağlanan geri bildirimi değiştirmek için denetleyiciye titreşim verileri de gönderebilirsiniz. Denetleyici, değerleri XInputSetState işlevine geçirerek bağımsız olarak kontrol edilebilen iki titreşim motoru içerir.

Her motorun hızı, aşağıdaki gibi XInputSetState işlevine aktarılan XINPUT_VIBRATION yapısında bir WORD değeri kullanılarak belirtilebilir.

XINPUT_VIBRATION vibration;
ZeroMemory( &vibration, sizeof(XINPUT_VIBRATION) );
vibration.wLeftMotorSpeed = 32000; // use any value between 0-65535 here
vibration.wRightMotorSpeed = 16000; // use any value between 0-65535 here
XInputSetState( i, &vibration );

Sağ motorun yüksek frekanslı motor, sol motorun düşük frekanslı motor olduğunu unutmayın. Farklı efektler sağladığından her zaman aynı miktarda ayarlanması gerekmez.

Ses Cihazı Tanımlayıcılarını Alma

Bir denetleyicinin mikrofonlu kulaklığı şu işlevlere sahiptir:

  • Mikrofon kullanarak ses kaydetme
  • Kulaklık kullanarak sesi geri çalma

Kulaklığın cihaz tanımlayıcılarını almak için bu kodu kullanın:

WCHAR renderId[ 256 ] = {0};
WCHAR captureId[ 256 ] = {0};
UINT rcount = 256;
UINT ccount = 256;

XInputGetAudioDeviceIds( i, renderId, &rcount, captureId, &ccount );

Cihaz tanımlayıcılarını aldıktan sonra uygun arabirimleri oluşturabilirsiniz. Örneğin, XAudio 2.8 kullanıyorsanız, bu cihaz için bir ana ses oluşturmak için şu kodu kullanın:

IXAudio2* pXAudio2 = NULL;
HRESULT hr;
if ( FAILED(hr = XAudio2Create( &pXAudio2, 0, XAUDIO2_DEFAULT_PROCESSOR ) ) )
    return hr;

IXAudio2MasteringVoice* pMasterVoice = NULL;
if ( FAILED(hr = pXAudio2->CreateMasteringVoice( &pMasterVoice, XAUDIO2_DEFAULT_CHANNELS, XAUDIO2_DEFAULT_SAMPLERATE, 0, renderId, NULL, AudioCategory_Communications ) ) )
    return hr;

captureId cihaz tanımlayıcısını kullanma hakkında bilgi için bkz. Akış yakalama.

DirectSound GUID'lerini alma (yalnızca eski DirectX SDK'sı)

Bir denetleyiciye bağlanabilen mikrofonlu kulaklığın iki işlevi vardır: mikrofon kullanarak ses kaydedebilir ve kulaklık kullanarak sesi çalabilir. XInput API'sinde, bu işlevler IDirectSound8 ve IDirectSoundCapture8 arabirimleri kullanılarak DirectSoundaracılığıyla gerçekleştirilir.

Mikrofonlu kulaklık mikrofonunu ve kulaklığını uygun DirectSound arabirimleriyle ilişkilendirmek için, XInputGetDSoundAudioDeviceGuidsçağırarak yakalama ve işleme cihazları için DirectSoundGUID'leri almanız gerekir.

Dikkat

Eski DirectSound kullanılması önerilmez ve Windows Mağazası uygulamalarında kullanılamaz. Bu bölümdeki bilgiler yalnızca XInput'un DirectX SDK sürümü (XInput 1.3) için geçerlidir. XInput'un (XInput 1.4) Windows 8 sürümü, XInputGetAudioDeviceIdsaracılığıyla alınan Windows Ses Oturumu API'si (WASAPI) cihaz tanımlayıcılarını kullanır.

XInputGetDSoundAudioDeviceGuids( i, &dsRenderGuid, &dsCaptureGuid );

GUID'leri aldıktan sonra, DirectSoundCreate8 ve DirectSoundCaptureCreate8'i şu şekilde çağırarak uygun arabirimleri oluşturabilirsiniz:

// Create IDirectSound8 using the controller's render device
if( FAILED( hr = DirectSoundCreate8( &dsRenderGuid, &pDS, NULL ) ) )
   return hr;

// Set coop level to DSSCL_PRIORITY
if( FAILED( hr = pDS->SetCooperativeLevel( hWnd, DSSCL_NORMAL ) ) )
   return hr;

// Create IDirectSoundCapture using the controller's capture device
if( FAILED( hr = DirectSoundCaptureCreate8( &dsCaptureGuid, &pDSCapture, NULL ) ) )
   return hr;

Programlama Referansı

  • Last updated on