ใช้ไลบรารีเกมคอนโทรลเลอร์

ใช้ฟังก์ชันต่อไปนี้เพื่อเพิ่มการรองรับเกมคอนโทรลเลอร์ลงในเกมโดยใช้ไลบรารีเกมคอนโทรลเลอร์

เริ่มต้นและทำลายไลบรารีเกมคอนโทรลเลอร์

ใช้ฟังก์ชัน Paddleboat_init เพื่อเริ่มต้นไลบรารีเกมคอนโทรลเลอร์

Paddleboat_ErrorCode Paddleboat_init(JNIEnv *env, jobject jcontext)

Paddleboat_init ใช้พารามิเตอร์ 2 รายการดังนี้

  • ตัวชี้ไปยัง JNIEnv ที่แนบมากับชุดข้อความปัจจุบัน
  • การอ้างอิงออบเจ็กต์ JNI jobject ไปยังคลาสที่ได้มาจาก Context ออบเจ็กต์คลาสที่ได้มา Context ใดๆ ก็ตามจะถูกต้อง ซึ่งรวมถึงแต่ไม่จำกัดเพียง Activity, NativeActivity หรือ GameActivity

Paddleboat_init จะแสดงผล PADDLEBOAT_NO_ERROR หากการเริ่มต้นสำเร็จ ไม่เช่นนั้นระบบจะแสดงรหัสข้อผิดพลาดที่เหมาะสม

คุณสามารถใช้ Paddleboat_isInitialized เพื่อตรวจสอบว่าไลบรารี Game Controller เริ่มต้นเรียบร้อยแล้วหรือไม่ โดยจะแสดงผลเป็นค่าบูลีน หากเป็นจริง แสดงว่า API พร้อมใช้งาน

bool Paddleboat_isInitialized()

ก่อนสิ้นสุดแอปพลิเคชัน ให้ใช้ฟังก์ชัน Paddleboat_destroy เพื่อปิดไลบรารีเกมคอนโทรลเลอร์ ฟังก์ชันนี้ใช้พารามิเตอร์เดียว ซึ่งเป็นตัวชี้ไปยัง JNIEnv ที่แนบมากับชุดข้อความปัจจุบัน คุณจะเรียกใช้ Paddleboat_init ได้อีกครั้งหลังวันที่ Paddleboat_destroy

void Paddleboat_destroy(JNIEnv *env)

แจ้งไลบรารีเกี่ยวกับเหตุการณ์ในวงจร

ไลบรารีเกมคอนโทรลเลอร์ต้องได้รับแจ้งเกี่ยวกับเหตุการณ์วงจรกิจกรรม onStop และ onStart เรียกใช้ฟังก์ชัน Paddleboat_onStop และ Paddleboat_onStart จากโค้ดการจัดการเหตุการณ์หยุดและเริ่ม ทั้ง 2 ฟังก์ชันใช้พารามิเตอร์เดียว ซึ่งก็คือตัวชี้ไปยัง JNIEnv ที่แนบกับชุดข้อความปัจจุบัน

void Paddleboat_onStop(JNIEnv *env)
void Paddleboat_onStart(JNIEnv *env)

ลงทะเบียนหรือนำ Callback สถานะของตัวควบคุมออก

ไลบรารี Game Controller จะใช้ Callback สถานะของคอนโทรลเลอร์เพื่อแจ้งเตือนเกมเมื่อมีการเชื่อมต่อหรือยกเลิกการเชื่อมต่อคอนโทรลเลอร์ โดยรองรับ Callback สถานะตัวควบคุมได้ครั้งละ 1 รายการเท่านั้น

  • หากต้องการลงทะเบียน Callback สถานะตัวควบคุมหรือแทนที่ Callback ที่ลงทะเบียนไว้ก่อนหน้านี้ด้วยฟังก์ชัน Callback ใหม่ ให้เรียกใช้ฟังก์ชัน Paddleboat_setControllerStatusCallback
  • หากต้องการนำ Callback ที่ลงทะเบียนไว้ในปัจจุบันออก ให้ส่ง NULL หรือ nullptr
  • พารามิเตอร์ userData เป็นตัวชี้ที่ไม่บังคับไปยังข้อมูลที่ผู้ใช้กำหนด ระบบจะส่งพารามิเตอร์ userData ไปยังฟังก์ชัน Callback ตัวชี้จะเก็บไว้ภายในจนกว่าจะมีการเปลี่ยนแปลงโดยการเรียก Paddleboat_setControllerStatusCallback ในภายหลัง
void Paddleboat_setControllerStatusCallback(Paddleboat_ControllerStatusCallback
  statusCallback, void *userData)

ลายเซ็นของฟังก์ชัน Callback คือ

typedef void (*Paddleboat_ControllerStatusCallback)(
  const int32_t controllerIndex,
  const Paddleboat_ControllerStatus controllerStatus,
  void *userData)
พารามิเตอร์ คำอธิบาย
controllerIndex ดัชนีของตัวควบคุมที่เริ่มการเรียกกลับ จะเป็นค่าระหว่าง 0 ถึง
PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus ค่า enum เป็น PADDLEBOAT_CONTROLLER_JUST_CONNECTED หรือ
PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED
userData ตัวชี้ที่ไม่บังคับ (อาจเป็น NULL) ไปยังข้อมูลที่ผู้ใช้กำหนดซึ่งระบุโดยการเรียกใช้ Paddleboat_setControllerStatusCallback ครั้งล่าสุด

เรียกใช้ฟังก์ชันอัปเดตไลบรารีเกมคอนโทรลเลอร์

ควรเรียกใช้ฟังก์ชันอัปเดตไลบรารีเกมคอนโทรลเลอร์ Paddleboat_update 1 ครั้งต่อเฟรมเกม โดยควรเรียกใช้ใกล้กับจุดเริ่มต้นของเฟรม ฟังก์ชันนี้ใช้พารามิเตอร์เดียว ซึ่งเป็นตัวชี้ไปยัง JNIEnv ที่แนบมากับชุดข้อความปัจจุบัน

void Paddleboat_update(JNIEnv *env)

เหตุการณ์ในกระบวนการ

เมื่อได้รับเหตุการณ์การป้อนข้อมูล เกมของคุณจะต้องส่งต่อเหตุการณ์เหล่านั้นไปยังไลบรารีเกมคอนโทรลเลอร์เพื่อตรวจสอบ ไลบรารี Game Controller จะประเมินว่าเหตุการณ์การป้อนข้อมูลเชื่อมโยงกับอุปกรณ์ที่มีการจัดการรายการใดรายการหนึ่งหรือไม่ ระบบจะประมวลผลและใช้เหตุการณ์จากอุปกรณ์ที่มีการจัดการ

ไลบรารีเกมคอนโทรลเลอร์รองรับเหตุการณ์อินพุต 2 ประเภท ได้แก่ เหตุการณ์อินพุต AInputEvents และ GameActivity

การประมวลผล AInputEvent

เกมของคุณควรส่งต่อ AInputEvents โดยการเรียกใช้ Paddleboat_processInputEvent จากโค้ดการจัดการเหตุการณ์

int32_t Paddleboat_processInputEvent(const AInputEvent *event)

Paddleboat_processInputEvent จะแสดงผล 0 หากระบบละเว้นเหตุการณ์ และ 1 หากระบบประมวลผลและใช้เหตุการณ์โดยไลบรารีเกมคอนโทรลเลอร์

การประมวลผลเหตุการณ์ GameActivity

หากเกมของคุณใช้ GameActivity ให้ส่งต่อเหตุการณ์ GameActivityKeyEvent และ GameActivityMotionEvent โดยเรียกใช้ Paddleboat_processGameActivityKeyInputEvent หรือ Paddleboat_processGameActivityMotionInputEvent จากโค้ดการจัดการเหตุการณ์

int32_t Paddleboat_processGameActivityKeyInputEvent(const void *event,
                                                    const size_t eventSize)
int32_t Paddleboat_processGameActivityMotionInputEvent(const void *event,
                                                       const size_t eventSize)
พารามิเตอร์ คำอธิบาย
event ตัวชี้ไปยังโครงสร้าง GameActivityKeyEvent หรือ GameActivityMotionEvent ขึ้นอยู่กับฟังก์ชันที่เรียกใช้
eventSize ขนาดเป็นไบต์ของโครงสร้างเหตุการณ์ที่ส่งในพารามิเตอร์ event

ทั้ง 2 ฟังก์ชันจะแสดงผล 0 หากระบบละเว้นเหตุการณ์ และ 1 หากระบบประมวลผลและใช้เหตุการณ์โดยไลบรารีเกมคอนโทรลเลอร์

GameActivity ต้องระบุแกนการเคลื่อนไหวที่ใช้งานอยู่โดยใช้ฟังก์ชัน GameActivityPointerAxes_enableAxis การเรียกใช้ Paddleboat_getActiveAxisMask จะแสดงผลบิตมาสก์ของแกนการเคลื่อนไหวที่ใช้งานอยู่ในปัจจุบันซึ่งใช้โดยตัวควบคุมที่เชื่อมต่ออยู่

uint64_t Paddleboat_getActiveAxisMask()

ดูตัวอย่างวิธีจัดการปัญหานี้ได้ที่ตัวอย่างไลบรารีเกมคอนโทรลเลอร์ที่ใช้ GameActivity ตัวอย่างจะสำรวจมาสก์แกนที่ใช้งานอยู่และแจ้งให้ GameActivity ทราบเมื่อมีการใช้แกนใหม่ ซึ่งจะใช้ในฟังก์ชัน NativeEngine::CheckForNewAxis()

void NativeEngine::CheckForNewAxis() {
    // Tell GameActivity about any new axis ids so it reports
    // their events
    const uint64_t activeAxisIds = Paddleboat_getActiveAxisMask();
    uint64_t newAxisIds = activeAxisIds ^ mActiveAxisIds;
    if (newAxisIds != 0) {
        mActiveAxisIds = activeAxisIds;
        int32_t currentAxisId = 0;
        while(newAxisIds != 0) {
            if ((newAxisIds & 1) != 0) {
                LOGD("Enable Axis: %d", currentAxisId);
                GameActivityPointerAxes_enableAxis(currentAxisId);
            }
            ++currentAxisId;
            newAxisIds >>= 1;
        }
    }
}

ตัวควบคุมการอ่าน

ไลบรารีเกมคอนโทรลเลอร์ใช้ค่าดัชนีเพื่ออ้างอิงถึงคอนโทรลเลอร์ที่เฉพาะเจาะจง ค่าดัชนีที่ถูกต้องจะอยู่ในช่วง 0 ถึง PADDLEBOAT_MAX_CONTROLLERS - 1 ฟังก์ชัน Paddleboat_getControllerStatus จะกำหนดสถานะของดัชนีตัวควบคุมที่ระบุ

Paddleboat_ControllerStatus Paddleboat_getControllerStatus(
  const int32_t controllerIndex)

มีฟังก์ชัน 3 รายการสำหรับการอ่านข้อมูลจากตัวควบคุมที่เชื่อมต่อ

  • ฟังก์ชัน Paddleboat_getControllerName จะดึงชื่อของอุปกรณ์ควบคุม
  • ฟังก์ชัน Paddleboat_getControllerInfo จะดึงข้อมูลเกี่ยวกับอุปกรณ์ควบคุมเอง
  • ฟังก์ชัน Paddleboat_getControllerData จะดึงข้อมูลสถานะปัจจุบันของอินพุตตัวควบคุม

ชื่อตัวควบคุม

ฟังก์ชัน Paddleboat_getControllerName รับพารามิเตอร์อินพุต 3 รายการ ได้แก่ ดัชนีตัวควบคุม ขนาดบัฟเฟอร์ และตัวชี้ไปยังบัฟเฟอร์เพื่อจัดเก็บสตริงชื่อตัวควบคุม สตริงชื่อจะจัดรูปแบบเป็นสตริง C โดยใช้การเข้ารหัส UTF-8 ชื่อของอุปกรณ์จะได้รับภายในโดยใช้ InputDevice.getName()

หาก Paddleboat_getControllerName ดึงข้อมูลชื่อได้สำเร็จ ระบบจะแสดงผล PADDLEBOAT_NO_ERROR มิเช่นนั้นจะแสดงรหัสข้อผิดพลาดที่เหมาะสม

Paddleboat_ErrorCode Paddleboat_getControllerName(const int32_t controllerIndex,
                                                  const size_t bufferSize,
                                                  char *controllerName);
พารามิเตอร์ คำอธิบาย
controllerIndex ดัชนีของตัวควบคุมที่เริ่มการเรียกกลับ จะเป็นค่าระหว่าง 0 ถึง
PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize ขนาดเป็นไบต์ของบัฟเฟอร์ที่ส่งโดย controllerName ระบบจะตัดสตริงชื่อหากจำเป็นเพื่อให้พอดีกับบัฟเฟอร์
controllerName ตัวชี้ไปยังบัฟเฟอร์ขนาด bufferSize ไบต์เพื่อจัดเก็บชื่อตัวควบคุม ระบบจะจัดเก็บชื่อเป็นสตริง C โดยใช้การเข้ารหัส UTF-8

ข้อมูลอุปกรณ์ควบคุม

ฟังก์ชัน Paddleboat_getControllerInfo จะใช้พารามิเตอร์อินพุต 2 รายการ ได้แก่ ดัชนีตัวควบคุมและตัวชี้ไปยังโครงสร้าง Paddleboat_Controller_Info

หาก Paddleboat_Controller_Info มีข้อมูลอยู่แล้ว Paddleboat_getControllerInfo จะแสดงผล PADDLEBOAT_NO_ERROR มิเช่นนั้นจะแสดงรหัสข้อผิดพลาดที่เหมาะสม

Paddleboat_ErrorCode Paddleboat_getControllerInfo(const int32_t controllerIndex,
  Paddleboat_Controller_Info *controllerInfo)

โครงสร้าง Paddleboat_Controller_Info มีข้อมูลเฉพาะอุปกรณ์เกี่ยวกับตัวควบคุม

typedef struct Paddleboat_Controller_Info {
    uint32_t controllerFlags;
    int32_t controllerNumber;
    int32_t vendorId;
    int32_t productId;
    int32_t deviceId;
    Paddleboat_Controller_Thumbstick_Precision leftStickPrecision;
    Paddleboat_Controller_Thumbstick_Precision rightStickPrecision;
} Paddleboat_Controller_Info;

typedef struct Paddleboat_Controller_Thumbstick_Precision {
    float stickFlatX;
    float stickFlatY;
    float stickFuzzX;
    float stickFuzzY;
} Paddleboat_Controller_Thumbstick_Precision;

สมาชิกโครงสร้างหลายรายการจะได้รับการป้อนข้อมูลด้วยค่าที่นำมาจาก InputDevice ที่เชื่อมโยงกับตัวควบคุม ดังนี้

controllerNumber    -   InputDevice.getControllerNumber()
vendorId              - InputDevice.getVendorId()
productId             - InputDevice.getProductId()
deviceId              - InputDevice.getId()
  • ค่า stickFlat แสดงถึงขอบเขตของตำแหน่งแบนราบตรงกลาง ค่านี้มีประโยชน์เป็นหลักในการคำนวณ "เดดโซน" ตรงกลางเริ่มต้นในอุปกรณ์ที่ปรับศูนย์กลางอัตโนมัติ
  • ค่า stickFuzz แสดงถึงความคลาดเคลื่อนที่ยอมรับได้ หรือค่าปัจจุบันอาจเบี่ยงเบนจากค่าจริงได้มากน้อยเพียงใดเนื่องจากสัญญาณรบกวนและข้อจำกัดด้านความไวของอุปกรณ์

ค่าทั้ง 2 ค่าจะได้รับการปรับให้เป็นมาตรฐานตามค่าแกนสูงสุดที่ 1.0 ในมิติข้อมูลใดมิติข้อมูลหนึ่ง

สมาชิก controllerFlags มีชุดค่าผสมของแฟล็กที่มาสก์บิตแต่ละรายการและค่าชุดค่าผสมหลายบิต

การดำเนินการ AND เชิงตรรกะของ controllerFlags ด้วย PADDLEBOAT_CONTROLLER_LAYOUT_MASK จะส่งผลให้เกิดค่าที่อาจแคสต์ไปยัง enum Paddleboat_ControllerButtonLayout Enum นี้ระบุไอคอนและเลย์เอาต์ของปุ่มที่ตัวควบคุมใช้

enum Paddleboat_ControllerButtonLayout {
    //  Y
    // X B
    //  A
    PADDLEBOAT_CONTROLLER_LAYOUT_STANDARD = 0,
    //  △
    // □ ○
    //  x
    PADDLEBOAT_CONTROLLER_LAYOUT_SHAPES = 1,
    //  X
    // Y A
    //  B
    PADDLEBOAT_CONTROLLER_LAYOUT_REVERSE = 2,
    // X Y R1 L1
    // A B R2 L2
    PADDLEBOAT_CONTROLLER_LAYOUT_ARCADE_STICK = 3,
    PADDLEBOAT_CONTROLLER_LAYOUT_MASK = 3
};

ค่าคงที่ต่อไปนี้จะกำหนดบิตความสามารถ หากต้องการตรวจสอบว่าตัวควบคุมรองรับความสามารถหนึ่งๆ หรือไม่ ให้ดำเนินการ AND เชิงตรรกะของค่าคงที่ที่เกี่ยวข้องกับ controllerFlags ผลลัพธ์ที่ไม่ใช่ 0 หมายความว่าตัวควบคุมรองรับความสามารถดังกล่าว

PADDLEBOAT_CONTROLLER_FLAG_TOUCHPAD

หากตั้งค่าบิตแฟล็กนี้ ตัวควบคุมจะมีทัชแพดในตัว หากกดทัชแพด ตัวควบคุมจะตั้งค่าบิต PADDLEBOAT_BUTTON_TOUCHPAD ในช่อง Paddleboat_Controller_Data.buttonsDown

PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE

หากตั้งค่าบิตแฟล็กนี้ ตัวควบคุมจะจำลองอุปกรณ์ชี้ตำแหน่ง ระบบจะป้อนพิกัดปัจจุบันของตัวชี้เสมือนลงในสมาชิก virtualPointer ของโครงสร้าง Paddleboat_Controller_Data

ข้อมูลผู้ควบคุม

ฟังก์ชัน Paddleboat_getControllerData จะใช้พารามิเตอร์อินพุต 2 รายการ ได้แก่ ดัชนีตัวควบคุมและตัวชี้ไปยังโครงสร้าง Paddleboat_Controller_Data หาก Paddleboat_Controller_Data มีข้อมูลอยู่ Paddleboat_getControllerData จะแสดงผลเป็น PADDLEBOAT_NO_ERROR มิเช่นนั้นระบบจะแสดงรหัสข้อผิดพลาดที่เหมาะสม

Paddleboat_ErrorCode Paddleboat_getControllerData(const int32_t controllerIndex,
  Paddleboat_Controller_Data *controllerData)

โครงสร้าง Paddleboat_Controller_Data มีค่าอินพุตการควบคุมปัจจุบันของตัวควบคุม

typedef struct Paddleboat_Controller_Data {
    uint64_t timestamp;
    uint32_t buttonsDown;
    Paddleboat_Controller_Thumbstick leftStick;
    Paddleboat_Controller_Thumbstick rightStick;
    float triggerL1;
    float triggerL2;
    float triggerR1;
    float triggerR2;
    Paddleboat_Controller_Pointer virtualPointer;
} Paddleboat_Controller_Data;

typedef struct Paddleboat_Controller_Pointer {
    float pointerX;
    float pointerY;
} Paddleboat_Controller_Pointer;

typedef struct Paddleboat_Controller_Thumbstick {
    float stickX;
    float stickY;
} Paddleboat_Controller_Thumbstick;

ช่วงค่า

ประเภทอินพุต ช่วงค่า
แกนปุ่มทัมบ์สติ๊ก -1.0 ถึง 1.0
ทริกเกอร์ 0.0 ถึง 1.0
เคอร์เซอร์เสมือนจริง 0.0 เป็นความกว้าง/ความสูงของหน้าต่าง (เป็นพิกเซล)

รายละเอียดโครงสร้าง

สมาชิกในบ้าน คำอธิบาย
buttonsDown อาร์เรย์บิตฟิลด์แบบบิตต่อปุ่ม ค่าคงที่บิตมาสก์ของปุ่มจะกำหนดไว้ในไฟล์ส่วนหัว paddleboat.h และขึ้นต้นด้วย PADDLEBOAT_BUTTON_
timestamp การประทับเวลาของเหตุการณ์อินพุตของตัวควบคุมล่าสุด การประทับเวลาคือไมโครวินาทีนับตั้งแต่ Epoch ของนาฬิกา
virtualPointer ตำแหน่งเคอร์เซอร์เสมือน ใช้ได้เฉพาะเมื่อตั้งค่าแฟล็ก PADDLEBOAT_CONTROLLER_FLAG_VIRTUAL_MOUSE ใน controllerFlags เท่านั้น มิฉะนั้นจะเป็น 0.0, 0.0