Serwis Edukacyjny
Nauczycieli
w I-LO w Tarnowie

obrazek

Materiały dla uczniów liceum

  Wyjście       Spis treści       Wstecz       Dalej  

Autor artykułu: mgr Jerzy Wałaszek

©2021 mgr Jerzy Wałaszek
I LO w Tarnowie

SDL2

Interfejs SDL2:

SDL_RWops

SPIS TREŚCI

Rozdział jest tłumaczeniem oryginalnej instrukcji dla biblioteki SDL2. Oryginał znajdziesz pod tym adresem: https://wiki.libsdl.org/CategoryAPI.

SDL_RWops

Struktura dostarczająca abstrakcyjnego interfejsu do strumienia we/wy. Aplikacje mogą ogólnie ignorować szczegóły wewnętrznych elementów tej struktury i traktować je jako mętne wskaźniki. Jednakże szczegóły te są istotne do kodowania na niskim poziomie, gdzie może wystąpić potrzeba implementacji jednego z nich.

Pola danych

Sint64 (*)(SDL_RWops *) size funkcja wywoływana zwrotnie podająca rozmiar strumienia; zobacz do Uwag.
Sint64 (*)(SDL_RWops *, Sint64, int) seek funkcja wywoływana zwrotnie przesuwająca pozycję w strumieniu; zobacz do Uwag.
size_t (*)(SDL_RWops *, void *, size_t, size_t) read funkcja wywoływana zwrotnie odczytująca ze strumienia; zobacz do Uwag.
size_t (*)(SDL_RWops *, const void *, size_t, size_t) write funkcja wywoływana zwrotnie zapisująca do strumienia; zobacz do Uwag.
int (*)(SDL_RWops *) close funkcja wywoływana zwrotnie zamykająca strumień; zobacz do Uwag.
Uint32 type rodzaj strumienia; zobacz do Uwag.
union hidden dane specyficzne dla strumienia; zobacz do Uwag.

Przykładowy kod

SDL_RWops *io = SDL_RWFromFile("username.txt", "rb");
if (io != NULL)
{
    char name[256];
    if (io->read(io, name, sizeof (name), 1) > 0)
    {
        printf("Hello, %s!\n", name);
    }
    io->close(io);
}

Poniższy przykład działa identycznie, lecz używa zalecanego interfejsu makr.

SDL_RWops *io = SDL_RWFromFile("username.txt", "rb");
if (io != NULL)
{
    char name[256];
    if (SDL_RWread(io, name, sizeof (name), 1) > 0)
    {
        printf("Hello, %s!\n", name);
    }
    SDL_RWclose(io);
}

Uwagi

Struktura SDL_RWops stanowi abstrakcję we/wy. Udostępnia interfejs do odczytu, zapisu i poszukiwania danych w strumieniu bez potrzeby znajomości ich źródła.

Na przykład, struktura RWops może zostać ustawiona na bufor w pamięci, plik na dysku lub połączenie z serwerem sieciowym bez żadnej zmiany w sposobie obsługi transferów danych przez użytkownika.

SDL udostępnia kilka wewnętrznych metod odczytu ze standardowych typów strumieni, takich jak pliki i bufory pamięciowe, lecz ta struktura może być wykorzystywana przez aplikację lub obce biblioteki do implementacji zupełnie dowolnych rodzajów strumieni,

Większość pól w tej strukturze jest wskaźnikami do funkcji, które są używane jako funkcje wywoływane zwrotnie do implementacji interfejsu danego strumienia. Wszystkie stosują konwencję wywołania SDLCALL.

Proszę zwrócić uwagę, iż wiele z tych wskaźników do funkcji używało typu int w SDL 1.2; aby dać im lepszy zakres, teraz stosują one typ Sint64 w SDL 2.0.

Aplikacje nie powinny się troszczyć o szczegóły wewnętrzne tej struktury. Mogą traktować je jako mętne wskaźniki i używać z nimi funkcji SDL_RWread(), SDL_RWwrite(), SDL_RWseek(), SDL_RWtell() i SDL_RWclose(). W istocie aplikacje prawie nigdy nie modyfikują tych struktur, faworyzując tworzenie w zastępstwie funkcji takich jak SDL_RWFromFile(), SDL_RWFromMem(), itp.

Obce biblioteki i kod niskopoziomowy muszą jednakże posiadać wiedzę na temat właściwej implementacji tej struktury.

Funkcja Rozmiaru

Pole size jest wskaźnikiem do funkcji, która zgłasza całkowity rozmiar strumienia w bajtach. Jeśli rozmiar strumienia nie może zostać określony (albo ponieważ nie ma to sensu dla danego rodzaju strumienia, albo z powodu wystąpienia jakiegoś błędu), funkcja ta zwraca -1.

Funkcja Przesuwająca Pozycję

Pole seek jest wskaźnikiem do funkcji, która ustawia pozycję następnych operacji odczytu/zapisu w strumieniu. Pozycja zmieniana jest w przesunięciach bajtowych. Jeśli strumień nie może zmienić pozycji (albo ponieważ nie ma to sensu dla danego rodzaju strumienia, albo z powodu wystąpienia jakiegoś błędu), funkcja zwraca -1, w przeciwnym razie zwraca nową pozycję. Przesunięcie zero bajtów od RW_SEEK_CUR jest typowym sposobem określenia bieżącej pozycji w strumieniu.

Końcowy argument pracuje tak jak w standardowej funkcji fseek() "whence":

Identyfikator Wartość Wyjaśnienie
RW_SEEK_SET 0 Przesuń od początku danych.
RW_SEEK_CUR 1 Przesuń względem bieżącego punktu odczytu.
RW_SEEK_END 2 Przesuń względem końca danych.

Funkcja Odczytu

Pole read jest wskaźnikiem do funkcji, która odczytuje ze strumienia. Odczyt dotyczy maksymalnie num obiektów, każdy o rozmiarze size bajtów. Dane są odczytywane do bufora wskazywanego przez ptr. Zwraca liczbę odczytanych obiektów, która może być mniejsza od żądanej. Zwraca 0 w przypadku błędu lub osiągnięcia końca danych EOF.

Funkcja Zapisu

Pole write jest wskaźnikiem do funkcji, która zapisuje do strumienia. Zapisuje ona dokładnie num obiektów, każdy o rozmiarze size bajtów, z bufora wskazywanego przez ptr. Zwraca liczbę zapisanych obiektów, która będzie mniejsza od żądanej w przypadku błędu.

Funkcja Zamykania

Pole close jest wskaźnikiem do funkcji, która czyści strumień. Powinna ona zwolnić wszystkie zasoby używane przez strumień oraz zwolnić samą strukturę SDL_RWops za pomocą SDL_FreeRW(). Zwraca 0 przy sukcesie, lub -1 przy błędzie. Po tym wywołaniu struktura SDL_RWops przestaje być ważna, nawet w przypadku błędu.

Rodzaj Strumienia

Pole type przyjmuje obecnie jedną z poniższych wartości, które aplikacja może zwykle ignorować:

Identyfikator Wartość Opis
SDL_RWOPS_UNKNOWN 0 Nieznany rodzaj strumienia lub rodzaj określony przez aplikację.
SDL_RWOPS_WINFILE 1 Uchwyt pliku Win32.
SDL_RWOPS_STDFILE 2 stdio.h FILE*.
SDL_RWOPS_JNIFILE 3 Plik w systemie Android.
SDL_RWOPS_MEMORY 4 Strumień pamięciowy (zapis/odczyt).
SDL_RWOPS_MEMORY_RO 5 Strumień pamięciowy (tylko odczyt).

Aplikacje i biblioteki wprowadzające swoje własne implementacje struktury RWops powinny stosować SDL_RWOPS_UNKNOWN. Wszystkie pozostałe wartości są obecnie zarezerwowane dla wewnętrznego użytku w SDL.

Ukryta Unia

Aplikacje mogą zupełnie zignorować tę unię. Wszystkie jej pola są zależne od platformy i intensywnie używane wewnętrznie przez SDL z jednym wyjątkiem. Możesz używać nieznanej struktury do przechowywania swoich własnych danych w implementacjach RWops, być może usuwając je podczas metody zamykania. Jeśli twoich danych nie da się zmieścić w tych dwóch wskaźnikach, użyj ich do przechowywania adresu struktury, która zawiera rzeczywiste dane.

Powiązane funkcje

Na początek:  podrozdziału   strony 

Zespół Przedmiotowy
Chemii-Fizyki-Informatyki

w I Liceum Ogólnokształcącym
im. Kazimierza Brodzińskiego
w Tarnowie
ul. Piłsudskiego 4
©2021 mgr Jerzy Wałaszek

Materiały tylko do użytku dydaktycznego. Ich kopiowanie i powielanie jest dozwolone
pod warunkiem podania źródła oraz niepobierania za to pieniędzy.

Pytania proszę przesyłać na adres email: i-lo@eduinf.waw.pl

Serwis wykorzystuje pliki cookies. Jeśli nie chcesz ich otrzymywać, zablokuj je w swojej przeglądarce.

Informacje dodatkowe.