Dessin de Surfaces

Dans certains cas, vous souhaiterez ne pas dessiner directement à l'écran mais plutôt sur un canevas qui pourra ulérieurement être réutilisé pour dessiner d'autres choses sur l'écran. Ce type de canevas est appelé une surface. Par exemple, imaginons que vous souhaitiez que l'utilisateur puisse dessiner sur l'écran. Il ne devra pas pouvoir le faire directement sur l'écran (car le dessin sera supprimé à chaque nouveau step). Vous souhaiterez donc que le dessin soit fait sur une surface distincte qui sera ensuite copiée à l'écran à chaque step. Ou bien encore vous voudrez utiliser une texture qui devra changer à intervalles réguliers.

L'utilisation de surfaces vous permettra de réaliser tout ceci et de plus, c'est assez simple à utiliser. Vous devrez créer en premier lieu une surface. Ensuite, vous indiquerez les opérations de dessin qui devront s'afficher sur cette surface. A partir de ce moment là, toutes les fonctions de dessin opéreront sur la surface en question. Une fois que vous en aurez terminé, vous réinitialiserez la cible de dessin et les opérations de dessin ultérieurs s'afficheront de nouveau sur cet écran. Vous pouvez dessiner sur la surface de l'écran de différentes manières ou encore utiliser la surface comme une texture. A ce sujet, il y a certaines choses pour lesquelles vous devrez être prudent. Veuillez consulter les remarques à la fin de cette section.

Les fonctions suivantes existent et concernent les surfaces.

surface_create(w, h) Crée une surface de largeur et hauteur indiquées. Retourne l'ID de la surface qui devra être utilisé dans tous les appels ultérieurs de fonctions. Veuillez prendre note que la surface ne sera pas effacée. Ceci incombe à l'utilisateur de le faire délibérément (définissez-la comme une cible puis appellez la fonction d'effacement appropriée.)
surface_free(id) Libére la mémoire utilisée par la surface.
surface_exists(id) Retourne si la surface identifiée par l'ID indiqué existe déjà.

surface_get_width(id) Retourne la largeur de la surface.
surface_get_height(id) Retourne la hauteur de la surface.
surface_get_texture(id) Retourne la texture correspondant à la surface. Ceci peut être utilisé pour afficher des objets texturés avec l'image de la surface.

surface_set_target(id) Définit la surface indiquée comme étant la cible d'affichage. Ainsi, toutes les opérations futures d'affichages opéreront sur cette surface. Cette commande réinitialise la projection afin de couvrir simplement la surface.
surface_reset_target() Réinitialise la cible d'affichage sur l'écran de destination courant.

surface_getpixel(id, x, y) Retourne la couleur du pixel correspondant à la position (x,y) de la surface. A utiliser avec précaution car cela n'est pas très rapide.
surface_save(id, fname) Sauvegarde la surface en tant qu'image BMP dans le fichier de nom filename. Utile pour faire une copie d'écran de la surface.
surface_save_part(id, fname, x, y, w, h) Sauvegarde une partie de la surface dans le fichier de nom filename.

draw_surface(id, x, y) Affiche la surface à la position (x,y). (sans mélange de couleur (pas de fondu) ni transparence alpha).
draw_surface_stretched(id, x, y, w, h) Affiche la surface étendue à la région indiquée.
draw_surface_tiled(id, x, y) Affiche la surface sous forme de tuiles (tiles) de manière à ce qu'elle remplisse entièrement la room.
draw_surface_part(id, left, top, width, height, x, y) Affiche la partie indiquée de la surface avec origine en position (x,y).
draw_surface_ext(id, x, y, xscale, yscale, rot, color, alpha) Affiche la surface avec mise à l'échelle et orientation tout en utilisant une couleur de mélange (utilisez c_white pour ne pas avoir de couleur de fondu) et une transparency alpha (0 à 1).
draw_surface_stretched_ext(id, x, y, w, h, color, alpha) Affiche la surface étendue à la région indiquée. La couleur est celle de la couleur de fondu et alpha correspond aux paramétres de transparence.
draw_surface_tiled_ext(id, x, y, xscale, yscale, color, alpha) Affiche la surface sous forme de tuiles (tiled) de façon à remplir complétement la room mais désormais avec une mise à l'échelle à l'aide des facteurs xscale et yscale et un paramétrage de la couleur et de la transparence.
draw_surface_part_ext(id, left, top, width, height, x, y, xscale, yscale, color, alpha) Affiche la partie indiquée de la surface avec origine en position (x,y) mais maintenant avec une mise à l'échelle à l'aide des facteurs xscale et yscale et un paramétrage de la couleur et de la transparence.
draw_surface_general(id, left, top, width, height, x, y, xscale, yscale, rot, c1, c2, c3, c4, alpha) La fonction d'affichage la plus couramment utilisée. Elle affiche la partie indiquée de la surface avec origine en position (x,y) mais désormais avec une mise à l'échelle à l'aide des facteurs xscale et yscale, un angle de rotation rot, une couleur pour chacun des quatre vertices (supérieur gauche, supérieur droit, inférieur droit et inférieur gauche) et une valeur de transparence alpha.

surface_copy(destination, x, y, source) Effectue une copie de la surface source à la position (x,y) dans la surface de destination. (sans aucune possibilité de fondu ou de mélange de couleur).
surface_copy_part(destination, x, y, source, xs, ys, ws, hs) Copie la partie indiquée de la surface source à la position (x,y) dans la surface de destination. (sans fondu ni mélange de couleur).

Veuillez noter qu'il n'existe pas de fonction permettant de copier une partie de l'écran dans une surface (ceci est impossible en raison d'éventuelles différences de format entre l'écran et les surfaces). Si nécessaire, vous devrez définir une nouvelle surface comme destination de rendu puis réafficher la room. Vous pourrez ensuite utiliser les routines de copie de surfaces pour obtenir la partie qui vous intéresse.

Notez qu'il est cependant possible de créer des sprites et des arrière-plans à partir de surfaces. Pour plus d'informations sur ce sujet, veuillez consulter la section sur la modification des ressources (changing resources).

Certaines précautions doivent être prises lors de l'utilisation de ces fonctions. En particulier, faîtes bien attention aux choses suivantes :

• Vous ne devrez jamais modifier la cible d'affichage alors que vous dessinez actuellement sur l'écran soit en d'autres termes, ne jamais utiliser cette cible dans les événements d'affichages (drawing events). Cela pourrait poser de sérieux problèmes avec la projection et le viewport.
• Les surfaces ne fonctionnent pas correctement dans le mode 3D. Vous ne pouvez les utiliser alors que vous n'êtes pas dans le mode 3DD (en invoquant la fonction d3d_end() avant d'utiliser les surfaces mais une fois que vous réentrerez dans le mode 3D, les surfaces seront détruites.
• Pour des raisons de vitesse, la surface est conservée uniquement en mémoire vidéo. Aussi, vous pourriez perdre la surface si par exemple, vous modifiez la résolution d'écran ou encore si votre effaceur d'écrans se met en fonction.
• Les surfaces ne seront pas sauvegardées lorsque vous effectuerez une sauvegarde de votre jeu.