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

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

เริ่มต้นและทำลายไลบรารี Game Controller

ใช้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 เพื่อตรวจสอบว่าเกม เริ่มต้นไลบรารีตัวควบคุมสำเร็จแล้ว แสดงผลบูลีน หากจริง API จะพร้อมใช้งาน

bool Paddleboat_isInitialized()

ก่อนยุติแอปพลิเคชัน ให้ใช้ Paddleboat_destroy เพื่อปิดไลบรารีของ Game Controller ฟังก์ชันใช้เวลา ซึ่งเป็นตัวชี้ไปยัง 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)

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

ไลบรารีเกมคอนโทรลเลอร์ใช้การเรียกกลับสถานะตัวควบคุมเพื่อแจ้งเกม เมื่อมีการเชื่อมต่อหรือเลิกเชื่อมต่อตัวควบคุม รองรับตัวควบคุมได้เพียง 1 รายการเท่านั้น สถานะ 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	ดัชนีของตัวควบคุมที่เริ่ม Callback จะเป็นค่าระหว่าง 0 ถึง PADDLEBOAT_MAX_CONTROLLERS - 1
controllerStatus	ค่า enum ของ PADDLEBOAT_CONTROLLER_JUST_CONNECTED หรือ PADDLEBOAT_CONTROLLER_JUST_DISCONNECTED
userData	เคอร์เซอร์ที่ไม่บังคับ (อาจเป็นค่าว่าง) สำหรับผู้ใช้ ข้อมูลที่กำหนดไว้โดยการเรียกครั้งล่าสุด 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 หากเหตุการณ์ ประมวลผลและใช้งานโดยไลบรารี Game Controller

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 function ใช้พารามิเตอร์อินพุต 2 ตัว ได้แก่ ดัชนีตัวควบคุม ขนาดบัฟเฟอร์ และตัวชี้ไปยัง บัฟเฟอร์สำหรับจัดเก็บสตริงชื่อตัวควบคุม สตริงชื่อจะมีการจัดรูปแบบเป็น สตริง 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	ดัชนีของตัวควบคุมที่เริ่ม Callback จะเป็นค่าระหว่าง 0 ถึง PADDLEBOAT_MAX_CONTROLLERS - 1
bufferSize	ขนาดเป็นไบต์ของบัฟเฟอร์ที่ส่งผ่าน controllerName สตริงชื่อจะเป็น ถูกตัดให้สั้นลงหากจำเป็นเพื่อให้พอดีกับบัฟเฟอร์
controllerName	ตัวชี้ไปยังบัฟเฟอร์ขนาด bufferSize ไบต์ เพื่อจัดเก็บชื่อตัวควบคุมไว้ ชื่อจะ เป็นสตริง C โดยใช้การเข้ารหัส UTF-8

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

Paddleboat_getControllerInfo function รับพารามิเตอร์อินพุต 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 แสดงถึงขอบเขตของตำแหน่งกึ่งกลางแบบแบน โดยปกติค่านี้จะมีประโยชน์ในการคํานวณ "dead-zone" ที่กึ่งกลางเริ่มต้น ในวันที่ อุปกรณ์แบบ Self-centering
• ค่า 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_getControllerInfo จะแสดงผล 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;

ช่วงของค่า

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

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

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