Wayang SDL/Referensi

Dari IgosCenter

Langsung ke: Navigasi, Cari

Daftar isi

Referensi Singkat

Wayang_SDL adalah framework pemrograman games yang biasa disebut sprite. Menyesuaikan dengan lingkungan wayang kulit, maka ada lima abstraksi utama yaitu :

  • Kelir (background) : latar belakang yang bisa berganti-ganti memakai bitmap.
  • Wayang (sprite) : lakon yang bisa bergerak di atas kelir
  • Ukoro (text) : teks yang bisa bergerak di atas kelir
  • Gamelan (sound): memainkan lagu pengiring wayang.
  • Dalang (controller) : pengatur semua wayang

Berkas:Wayang Elemen Utama.png

Kelir

Kelir (layar / screen) adalah latar belakang dimana wayang akan dimainkan. Fungsi-fungsi yang disediakan kelir memakai prefix "k", dan diikuti perintah dalam bahasa Inggriss. Secara umum kelir menyediakan layanan untuk membuka layar dengan gambar latar belakang, dan juga menggambar bentuk-bentuk khusus. Gambar yang dibuat pada kelir akan menetap, tak bisa terhapus, kecuali dengan memuat ulang latar belakang (memakai fungsi kSetImage). Selengkapnya, kelompok fungsi kelir adalah:


int kOpen(int width, int height,

char *filename);


void kClose();

kOpen harus dipanggil pertama kali untuk membuka layar grafik, dengan ukuran dan nama file citra latar belakang (ekstensi jpg, png, bmp).


kClose dipanggil terakhir kali untuk menutup layar.

int kGetHeight();

int kGetWidth();

int kMinX();

int kMinY();

int kMaxX();

int kMaxY();

Fungsi-fungsi ini mengembalikan dimensi layar, dan koordinat minimum / maksimum. Pada kelir, koordinat (0,0) ada di tengah layar. Sumbu x minimum ada di bawah, dan sumbu y minimum ada di kiri (sesuai koordinat kartesian)
void kSetCaption(char* str) mengubah judul layar (caption)
void kSetImage(char *fname); mengubah gambar latar belakang dengan file gambar baru
void kSetThickness(Uint16 t);

void kSetOpaque(Uint8 a);

void kSetColor(Uint32 color);

void kSetRGB(Uint8 r, Uint8 g,

Uint8 b);

void kSetBackground(Uint32

color);

void kSetBackRGB(Uint8 r,

Uint8 g, Uint8 b);

Perintah untuk mengubah pena yang akan dipakai untuk menggambar bentuk-bentuk dasar pada kelir.



void kPixel(Sint16 x, Sint16 y);

void kLine(Sint16 x1, Sint16 y1,

Sint16 x2, Sint16 y2 );


void kSquare(Sint16 x, Sint16 y,

Sint16 d);

void kFillSquare(Sint16 x,

Sint16 y, Sint16 d);


void kRectangle(Sint16 x, Sint16

y, Sint16 dx, Sint16 dy);

void kFillRectangle(

Sint16 x, Sint16 y,

Sint16 width, Sint16 height);


void kCircle(Sint16 x, Sint16 y,

Sint16 radius);

void kFillCircle(Sint16 x,

Sint16 y, Sint16 radius);


void kEllipse(Sint16 x, Sint16

y, Sint16 rx, Sint16 ry);

void kFillEllipse(

Sint16 x, Sint16 y,

Sint16 rx, Sint16 ry);


void kArc(Sint16 x, Sint16 y,

Sint16 radius,

float angle1, float angle2);

void kFillArc(Sint16 x,

Sint16 y, Sint16 radius,

float angle1, float angle2);

Perintah-perintah untuk menggambar bentuk dasar tertentu (titik, garis, bujur sangkar, persegi panjang, lingkaran, elips dan busur lingkaran), dengan menggunakan ketebalan serta warna yang telah diatur sebelumnya.

Versi biasa akan menggambar garis kerangka, sedang versi Fill akan menggambar isi benda.



Uint32 kGetPixel(Sint16 x,

Sint16 y);

void kSetPixelRGB(Sint16 x,

Sint16 y, Uint8 red,

Uint8 green, Uint8 blue);

void kSetPixelRGBA(Sint16 x,

Sint16 y, Uint8 red,

Uint8 green, Uint8 blue,

Uint8 alpha);

Fungsi khusus untuk membaca dan mengubah warna pixel pada gambar latar belakang.

Wayang

Wayang adalah gambar yang bisa bergerak diatas kelir. Wayang dibuat dengan memuat suatu file gambar. Setelah itu wayang bisa diminta berloncatan (jump) pada kelir untuk membuat efek animasi. Wayang juga bisa menggambar jejak (trail) dan mencetak diri sendiri (stamp) pada gambar layar belakang. Trail dan stamp akan menetap pada kelir, tak bisa terhapus sampai gambar latar belakang di-atur ulang.


hWayang wCreate(int nstate, ... );

hWayang wClone(hWayang w);

void wDelete(hWayang w);

Pertama kali wayang harus dibuat dengan fungsi wCreate dengan menyebutkan jumlah gambar (nstate) kemudia diikuti nama-nama file gambar (sebanyak nstate). Fungsi ini akan mengembalikan nilai hWayang, yang harus disimpan untuk akses ke fungsi-fungsi wayang lainnya. Jika nilai hWayang tidak valid, akan timbul "segmentation error".


Setelah wayang selesai bermain, bisa dihapus dengan wDelete. Sementara itu wClone digunakan untuk membuat banyak wayang yang serupa gambarnya.

Sint16 wGetState(hWayang w);

void wSetState(hWayang, int state);

void wNextState(hWayang);

void wBlink(hWayang, int repeat);

State merepresentasikan nomor gambar yang aktif (tampil). Nilainya bisa dari 0 hingga (nstate-1). Untuk mengubah state, gunakan fungsi wSetState, atau fungsi wNextState yang akan menaikkan state 1 tingkat, dan berputar kembali ke 0 setelah maksimum. Perubahan ini akan mengubah tampilan gambar wayang, sehingga muncul efek animasi.

Fungsi wBlink akan menganimaskan wayang sebanyak 'repeat' kali perubahan state, dengan periode 50 mili detik.

bool wIsHidden(hWayang w);

void wHide(hWayang w);

void hShow(hWayang w);

void wHideAll();

void wShowAll();

Wayang dapat nampak (shown) atau tak nampak (hidden) dengan pengaturan kedua fungsi ini.
void wSetTrail(hWayang w, Sint8 s);

void wChangeTrail(hWayang w,

Sint8 ds);


void wSetTrailColor(hWayang w,

Uint32 color);

void wSetTrailRGB(Wayang* w,

Uint8 r, Uint8 g, Uint8 b);

void wChangeTrailRGB(Wayang* w,

Sint16 dr, Sint16 dg,

Sint16 db);

void wSetTrailOpaque(Wayang* w,

Uint8 a);

void wChangeTrailOpaque(Wayang* w,

Uint8 da);

Trail adalah jejak yang akan ditinggalkan wayang saat bergerak (Move atau Step). Fungsi-fungsi kelompok ini mengatur ketebalan, warna, dan transparansi trail.

Fungsi jenis "set" akan mengubah atribut ke nilai parameter, sedang change menambahinya dengan nilai parameter.

void wScaleTo(hWayang w, double z);

void wScale(hWayang w, double dz);

Sint16 wGetH(hWayang w);

Sint16 wGetW(hWayang w);

Fungsi ini memperkecil atau memperbesar wayang dari ukuran normal (ukuran sebenarnya jika z=1).

Fungsi wGetW dan wGetH mengembalikan lebar dan tinggi wayang pada suatu saat. Nilai keduanya bisa berubah tergantung dimensi gambar (state), skala maupun sudut putaran wayang.

void wFlipX(hWayang w);

void wFlipY(hWayang w);

Membalik wayang pada sumbu X atau Y.
double wGetAngle(hWayang w);

void wTurnTo(hWayang w,

double angle);

void wTurn(hWayang w,

double degree);

Angle (sudut) menyatakan arah hadap wayang. Ini akan mempengaruhi tampilan, dan juga gerakan wayang (forward).
Sint16 wGetX(hWayang w);

Sint16 wGetY(hWayang w);

void wJumpTo(hWayang w,

Sint16 x, Sint16 y);

void wJump(hWayang w,

Sint16 dx, Sint16 dy);

void wJumpForward(hWayang w,

int distance);


sepasang fungsi wGetX dan wgetY mengembalikan posisi pusat wayang pada kelir sesuai koordinat kartesian. Harga X dan Y ini berubah jika wayang berpindah (jump, move atau step).

Fungsi wJumpTo() meloncat ke posisi absolut (x,y), sementara wJump() meloncat relatif berjarak (dx,dy) dari posisi awal. Sementara itu wJumpForward meloncat maju sejauh distance sesuai dengan arah menghadap (angle).

void wMoveTo(hWayang w,

Sint16 x, Sint16 y);

void wMove(hWayang w,

Sint16 dx, Sint16 dy);

void wMoveForward(hWayang w,

int distance);

Kelompok ini sama dengan kelompok jump, hanya saja seraya berpindah wayang akan meninggalkan trail, sesuai dengan pengaturan trail.
void wStepTo(hWayang w, Sint16 x,

Sint16 y, Sint16 speed);

void wStepForward(hWayang w,

int distance, int speed);

Berpindah sambil meninggalkan jejak, dengan kecepatan tertentu (dalam pixel per detik). Kalau tak ingin ada jejak, ubah trail menjadi 0.
Uint32 Uint32 wSay(hWayang w,

hUkoro p, Uint32 pause,

char* fmt, ...);

Wayang menyampaikan pesan, ditulis ke kelir dengan huruf sesuai Ukoro, dan akan hilang setelah pause mili detik.

Ukoro

Ukoro (kalimat/string) mewakili kata-kata di atas kelir. Mula-mula ukoro harus dibuat (create) dengan memilih nama file font (hanya bisa true type). Setelah itu Ukoro bisa dipakai untuk menulis langsung diatas kelir (seperti trail / stamp) yang menetap, atau dimunculkan (show) sehingga tampil terus pada posisi tertentu.


hUkoro uCreate(char* filename,

int size);

hUkoro uClone(hUkoro u);

void uDelete(hUkoro u);

Fungsi uCreate membuat ukoro baru dengan aksara (font) sesuai file, dan ukuran tertentu. Fungsi ini akan mengembalikan nilai hUkoro untuk akses ke fungsi-fungsi ukoro lainnya. Jika nilai hWayang tidak valid, akan timbul "segmentation error".


Ukoro bisa digandakan dengan uClone, dan dihapus dengan uDelete setelah selesai dipakai.

#define MODE_CENTER 0x1

#define MODE_LEFT 0x2

#define MODE_RIGHT 0x4

#define MODE_MID 0x10

#define MODE_TOP 0x20

#define MODE_BOTTOM 0x40

#define MODE_SHOW 0x80


void uSetMode(hUkoro u,

Uint8 mode);

void uUnsetMode(hUkoro u,

Uint8 mode);

Mengatur posisi tempilan teks sesuai mode yang telah didefinisikan.
bool uIsHidden(hWayang w);

void uHide(hWayang w);

void uShow(hWayang w);

Mengatur penampakan Ukoro.
void uSetText(hUkoro u, char *fmt, ...); uSetText mengubah teks yang ditampilkan dalam mode terlihat (SHOW). sementara itu uStamp akan mencetak teks itu ke kelir secara menetap.
void uPrintL(hUkoro p, Sint16 x,

Sint16 y, const char *str, ...);

void uPrintR(hUkoro p, Sint16 x,

Sint16 y, const char *str, ...);

void uPrintC(hUkoro p, Sint16 x,

Sint16 y, const char *str, ...);

Mencetak teks langsung ke layar pada posisi tertentu, dan akan menetap.
void wJumpTo(hWayang w,

Sint16 x, Sint16 y);

Memindah posisi Ukoro.

Gamelan

Gamelan adalah elemen yang memainkan gending (musik). Fungsi-fungsi yang disediakan meliputi:


hGamelan gCreate(int channel,

int max, ...);

hGamelan gClone(int channel);

void gDelete(hGamelan g);


Fungsi gCreate membuat gamelan baru pada suatu channel (dari 0 - 8). Pada setiap gamelan bisa didaftarkan max buah gending, berupa file audio (wav atau ogg). Pada satu saat, gamelan hanya dapat memainkan satu gending.

Meski demikian, beberapa gending dapat dimainkan bersamaan (suara akan tercampur) dengan membuat beberapa gending.


Gamelan berikutnya bisa dibuat dengan uClone. Daftar gending akan sama, namun channel harus berbeda. Setelah selesai, gamelan harus dihapus dengan fungsi gDelete.



void gPlay(hGamelan g,

int index, int loop);

void gStop(hGamelan g);

Fungsi untuk memainkan dan menghentikan gending pada gamelan.

Dalang

Dalam wayang kulit, dalang adalah manusia yang menggerakkan dan menyuarakan wayang. Pada SDL_Wayang, dalang merupakan kumpulan fungsi untuk :

  • Membaca waktu.
  • Membaca masukan keyboard.
  • Membaca masukan posisi mouse dan penekanan tombol mouse.
  • Kerangka dasar pemrograman event-driven (untuk game-loop).


void dSetPeriode(Uint32 t);

void dStart(Uint32 periode);

bool dNext();

void dFinish();

void dBreak();

Kelima fungsi ini penting untuk pemrograman event-driven. Kerangka dasar pemakaiannya adalah:


dStart(Uint32 periode);

do {

// lakukan proses disini

...

// jika ingin berhenti panggil

dBreak();

...

} while (dNext());

dFinish();



bool dIsMouse();

int dGetMouseX();

int dGetMouseY();

Dalam kerangka event-driven, dIsMouse memeriksa apakan tetikus (mouse) berpindah. Program dapat memproses perpindahan itu dengan membaca posisi mouse memakai dGetMouseX dan dGetMouseY
bool dIsButton();

int dGetButton();

int dGetButtonX();

int dGetButtonY();

Fungsi-fungsi ini untuk memproses event tombol mouse di-klik.
bool dIsKey();

Uint32 dGetKey();

Fungsi ini memproses jika kunci ditekan. Perhatikan event hanya terjadi saat kunci mulai ditekan. Jika kunci ditekan terus, harus diproses memakai dIsPressed bila event waktu tiba.
bool dIsTime();

Uint8 dIsPressed(key);


Fungsi ini memeriksa apakah event waktu sudah tiba, sesuai dengan periode loop (yang diset oleh dStart).
Uint32 dGetTicks();

Uint32 dPause(Uint32 t);

void dDelay(Uint32 t);


dGetTicks adalah fungsi untuk membaca waktu sejak program berjalan, dalam mili detik.


dPause menunda jalannya program selama t mili detik, atau ada penekanan kunci keyboard. Sementara itu dDelay menunda tanpa bisa dibatalkan penekanan kunci.

Tipe Data dan Operator

Tipe data bahasa C dan padanannya di SDL / Wayang_SDL adalah sebagai berikut.


Tipe C umum Tipe SDL panjang bit Minimum Maksimum Ketelitian
char Sint8 8 -128 127 1
short int Sint16 16 -32768 32767 1
int Sint32 32 -2147483648 2147483647 1
unsigned char Uint8 8 0 255 1
unsigned short Uint16 16 0 65535 1
unsigned int Uint32 32 0 4294967295 1
float 32 1.175494e-38 3.402823e+38 7 digit
double 64 2.225074e-308 1.797693e+308 15 digit
long double 96 3.362103e-4932 1.189731e+4932

Catatan:

Ini adalah data untuk kompiler GCC 32 bit di Linux. Panjang bit pada bahasa C bisa berbeda-beda tergantung kompiler dan sistem operasi. Panjang bit tipe SDL tetap.


Konstanta

Beberapa konstanta yang sering terpakai pada pemrograman Wayang_SDL.


Header Konstanta Penggunaan
wayang.h RED

YELLOW

GREEN

CYAN

BLUE

VIOLET

WHITE

BLACK

GREY

Untuk definisi color (24 bit). Bisa digunakan untuk fungsi-fungsi: kSetColor, wSetColor, uSetColor.
TRANSPARANT

OPAQUE

Definisi transparansi, gunakan untuk fungsi-fungsi: dsetOpaque, wSetTrailOpaque, uSetOpaque
MODE_CENTER

MODE_LEFT

MODE_RIGHT

MODE_MID

MODE_TOP

MODE_BOTTOM

MODE_SHOW

Mode tampilan Ukoro. Gunakan untuk fungsi: uSetMode, uUnsetMode.
SDL.h SDLK_UP

SDLK_LEFT

SDLK_RIGHT

SDLK_DOWN


SDLK_SPACE

Definisi papan kunci. Bisa digunakan untuk fungsi-fungsi dGetKey, dIsPressed.
math.h M_PI Definisi matematika PI (3.14....)



INT_MAX

RAND_MAX

Nilai maksimum integer dan bilangan random
NaN Not a Number, nilai tak valid floating point

Kontributor: Kocil

Diperoleh dari "http://saung.igoscenter.org/Wayang_SDL/Referensi"
(c) Igos Center Bandung, 2009