Jypelin käyttöohjeet » Kuvat ja niiden käsittely

Jypelissä kaikilla ruudulla näkyvillä olioilla (esimerkiksi GameObjectilla ja PhysicsObjectilla) on ominaisuus Image, joka kertoo, minkä näköinen olio on.

1. Kuvan lataaminen tiedostosta ja asettaminen oliolle

Yksinkertaisimmillaan kuva voidaan ladata sellaisenaan pelin LoadImage-aliohjelmalla kun se on ensin lisätty projektiin.

public class Peli : PhysicsGame
{
  Image olionKuva = LoadImage("kuvanNimi");
  
  public override void Begin()
  {
     //...
  }
}

Huomaa, että png-tunnistetta ei tarvitse laittaa kuvan nimen perään.

2. Kuvan lataaminen internetistä

Peli voi ladata kuvansa myös internetistä. Yksinkertaisimmillaan kuva voidaan asettaa oliolle seuraavasti:

DataStorage.DoWithURL("http://bit.ly/nl9BOr", olio.SetImage);

olio.SetImage on aliohjelma, jonka viite annetaan tässä toiselle aliohjelmalle DataStorage.DoWithURL. SetImage toimii tapahtumankäsittelijänä, joka suoritetaan kun kuva on ladattu. Toisin sanoen kuva ei ole ladattuna vielä tämän rivin (tai aliohjelman) suorituksen jälkeen, vaan Jypeli hoitaa sen taustalla samalla kun muuta pelin koodia suoritetaan.

Pidemmässä muodossa (ilman valmista SetImage-aliohjelmaa) kirjoitettuna sama olisi

DataStorage.DoWithURL("http://bit.ly/nl9BOr", AsetaKuva);

void AsetaKuva(StorageFile kuvaTiedosto)
{
   olio.Image = Image.FromFile(kuvaTiedosto);
}

Jos kuvalle halutaan tehdä muuta(kin) kuin asettaa se oliolle, kannattaa käyttää tätä muotoa.

Jypeli antaa oletuksena kuvalle 15 sekuntia aikaa ladata. Joissain tapauksissa tämä voi olla liikaa tai liian vähän, jolloin latausajan ylärajan voi antaa itse parametrina.

DataStorage.DoWithURL("http://bit.ly/nl9BOr", TimeSpan.FromSeconds(5), AsetaKuva);

Jos halutaan ladata useita kuvia netistä ja tehdä jotain vasta sen jälkeen kun kaikki kuvat on ladattu, se on mahdollista tehdä TriggerOnComplete-aliohjelmaa käyttäen.

DataStorage.TriggerOnComplete(
   JatkaLatausta,
   DataStorage.DoWithURL("http://images4.wikia.nocookie.net/__cb20101205222241/disney/images/0/07/Dewey.jpg", tupu.SetImage),
   DataStorage.DoWithURL("http://images2.wikia.nocookie.net/__cb20101205222431/disney/images/8/85/Huey.jpg", hupu.SetImage),
   DataStorage.DoWithURL("http://images2.wikia.nocookie.net/__cb20101205222760/disney/images/b/b7/Louie.jpg", lupu.SetImage)
);

void JatkaLatausta()
{
   // täällä oleva koodi suoritetaan kun kuvat on ladattu
}

Myös tässä tapauksessa on mahdollista säätää parametrilla, kuinka kauan odotetaan yksittäisen kuvan latautumista.

DataStorage.TriggerOnComplete(
   JatkaLatausta,
   TimeSpan.FromSeconds(5),
   DataStorage.DoWithURL("http://images4.wikia.nocookie.net/__cb20101205222241/disney/images/0/07/Dewey.jpg", tupu.SetImage),
   DataStorage.DoWithURL("http://images2.wikia.nocookie.net/__cb20101205222431/disney/images/8/85/Huey.jpg", hupu.SetImage),
   DataStorage.DoWithURL("http://images2.wikia.nocookie.net/__cb20101205222760/disney/images/b/b7/Louie.jpg", lupu.SetImage)
);

3. Projektiin liittämättömän kuvan lataaminen

Joskus voi tulla tarve ladata kuvia joita ei ole lisätty mukaan projektiin. Tähän soveltuu kutsu:

Image kuva = Image.FromFile("C:\\Users\\Mikko\\Kuvat\\kissa.png");

Huomaa kaksi \\-merkkiä tiedostopolussa. Kuva voi olla png-, jpeg- tai bmp- muotoinen.

Kannattaa kuitenkin huomioida että tämän käyttö vaikeuttaa pelin jakamista muille, sekä tulee pitää enemmän huolta polkujen oikeellisuuden suhteen. Tätä ei siis kannata käyttää, ellei ole aivan varma mitä on tekemässä.

4. Yksivärisen kuvan luominen

Yleensä kun halutaan tehdä oliosta yksivärinen, voidaan sen Color-ominaisuuteen asettaa tietty väriarvo. Joissain tapauksissa kuitenkin voidaan haluta tehdä tietyn kokoinen kuva, joka on vain yhtä väriä esimerkiksi pohjaksi muulle grafiikalle. Se onnistuu Image-luokan rakentajalla:

Image punainenKuva = new Image(200, 100, Color.Red);

5. Kahden tai useamman kuvan liittäminen yhdeksi

Kaksi erillistä kuvaa on mahdollista liittää yhteen joko vaaka- tai pystysuunnassa käyttämällä Image-luokan staattisia aliohjelmia TileHorizontal ja TileVertical.

Image valkoinen = new Image(80, 27, Color.White);
Image punainen = new Image(80, 27, Color.Red);
Image puolanLippu = Image.TileVertical(valkoinen, punainen);

Huomaa, että vaakasuunnassa liitettäessä kuvien korkeuden ja pystysuunnassa kuvien korkeuden on oltava samat.

Kuvia on myös mahdollista liittää peräkkäin useampia kuin yksi, mutta se vaatii useamman aliohjelmakutsun.

Image sininen = new Image(80, 18, Color.Blue);
Image valkoinen = new Image(80, 18, Color.White);
Image punainen = new Image(80, 18, Color.Red);

Image sinivalkoinen = Image.TileHorizontal(sininen, valkoinen);
Image ranskanLippu = Image.TileHorizontal(sinivalkoinen, punainen);

6. Yksittäisten pikselien asettaminen

Kuvan pikselidataan päästään käsiksi hakasulku- eli indeksointioperaattorin avulla. Yksittäisen pikselin väri saadaan kuvasta seuraavalla tavalla

Color pikselinVari = kuva[rivi, sarake];

Indekseistä rivi on pikselin paikka pysty- eli Y-suunnassa ja sarake vaaka- eli X-suunnassa. Toisin kuin pelimaailman koordinaateissa, tekstuurikoordinaateissa origo sijaitsee kuvan vasemmassa yläreunassa ja y-koordinaatti kasvaa alaspäin. Koordinaatit ovat positiivisia kokonaislukuja (rivi vähintään 0, enintään kuva.Height - 1 ja sarake vähintään 0 ja enintään kuva.Width - 1).

Pikselin värin voi asettaa seuraavanlaisella sijoituksella

kuva[rivi, sarake] = Color.Fuchsia;

tai mikä tahansa väri mikä halutaan pikselille antaa.

Lisää pikselitason kuvankäsittelystä löytyy Kuvankäsittely-sivulta.

7. Kuvan rajaaminen

Kuvasta voidaan rajata pienempi osa toiseen (tai samaan) muuttujaan käyttämällä sen Area-aliohjelmaa.

Image kuvanOsa = kuva.Area(10, 10, 20, 20);

Parametrit ovat järjestyksessä vasen reuna, yläreuna, oikea reuna ja alareuna. On huomattava, että alkuperäisen kuvan sisältö muuttuu jos rajattua kuvaa muutetaan! Jos tätä ei haluta, voidaan rajatusta kuvasta ottaa kopio

Image kuvanOsa = kuva.Area(10, 10, 20, 20).Clone();

8. Kuvan tai sen osien täyttäminen värillä

Image-luokka sisältää aliohjelman Fill kuvan täyttämiseen yksittäisellä värillä.

kuva.Fill(Color.Green);

Koko kuvan täyttäminen on harvemmin mielekästä, mutta Area-aliohjelman kanssa yhdistettynä kuvasta voidaan täyttää helposti suorakulmion muotoisia alueita.

Image suomenLippu = new Image(80, 54, Color.White);
suomenLippu.Area(0, 18, 79, 36).Fill( Color.Blue);
suomenLippu.Area(18, 0, 36, 53).Fill( Color.Blue);

9. Värin korvaaminen toisella värillä kuvassa

Kuvan valkoisten kohtien muuttaminen vihreiksi:

kuva.ReplaceColor(Color.White, Color.Green);

10. Kuvan tallentaminen tiedostoon

Kuva voidaan myös tallentaa tiedostoon tarvittaessa joko jpeg- tai png-muodossa.

DataStorage.Export(kuva.AsJpeg(), "kuva.jpg");

DataStorage.Export(kuva.AsPng(), "kuva.png");

Kuva tallentuu pelihakemiston (projektihakemiston alla yleensä bin) alle Data-alihakemistoon.

11. Miksi kuvani näyttää suttuiselta pelissä?

Käytät mahdollisesti liian pientä kuvaa. Jypeli skaalaa kuvan olion kokoiseksi, mutta se ei osaa tehdä siitä tarkempaa kuin se jo on. Kuvan skaalauskäytökseen voit vaikuttaa asettamalla

kuva.Scaling = ImageScaling.Nearest

tai

Nearest asetus on sopiva jos halutaan pikseligrafiikkaa, Linear taas kun halutaan että kuva mielummin "sumenee". Kannattaa kokeilla kumpi näyttää omassa pelissä paremmalta.

TODO: Tähän voisi laittaa esimerkit molemmista.

12. Miten saan muokattua pelin kuvaketta (ikonia)?

• Pelin hakemistossa on tiedosto Game.ico
• Avaa tiedosto vaikka Paint.Net:illä tai ihan Paintilla
• Muokkaa ikoni mieleiseksi
• Tallenna Game.png tiedostoksi