This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: SDBM_File, Next: SDL/App, Prev: Run, Up: Module List Tied access to sdbm files ************************* NAME ==== SDBM_File - Tied access to sdbm files SYNOPSIS ======== use SDBM_File; tie(%h, 'SDBM_File', 'Op.dbmx', O_RDWR|O_CREAT, 0640); untie %h; DESCRIPTION =========== See `tie', *Note Perlfunc: (perl.info)perlfunc,, `tie', *Note Perldbmfilter: (perl.info)perldbmfilter,  File: pm.info, Node: SDL/App, Next: SDL/Cdrom, Prev: SDBM_File, Up: Module List a SDL perl extension ******************** NAME ==== SDL::App - a SDL perl extension SYNOPSIS ======== $app = new SDL::App ( -title => 'FunkMeister 2000', -icon_title => 'FM2000', -icon => 'funkmeister.png', -width => 400, -height => 400 ); DESCRIPTION =========== This Object is a composite made up of a few surfaces, and strings. This object does the setup for the SDL library, and greates the base application window. The options that the constructor takes are: -title => the title bar of the window -icon_title => the title bar of the icon -icon => the icon image file -flags => the SDL_* surface flags for the default window -width => of the app window -height => of the app window -depth => the bit depth of the window Additional Methods ------------------ In addition to initilizing the SDL library, the app class provides access to a couple miscellaneous functions that all programs may need: $app->delay(milliseconds); Delay will cause a delay of roughly the specified milliseconds. Since this only runs in multi-tasking environments, the exact number is not assured. $app->ticks(); Ticks returns the number of clock ticks since the program was started. $app->error(); Error returns any pending SDL related error messages. It returns an empty string if no errors are pending, making it print friendly. $app->warp(x,y); Will move the cursor to the location x,y. AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::Surface(3) SDL::Mixer(3) SDL::Event(3) SDL::Cdrom(3).  File: pm.info, Node: SDL/Cdrom, Next: SDL/Cursor, Prev: SDL/App, Up: Module List a SDL perl extension ******************** NAME ==== SDL::Cdrom - a SDL perl extension SYNOPSIS ======== $cdrom = new SDL::Cdrom 0; DESCRIPTION =========== Cdrom.pm provides software control for CD music. To open a CD for playing, ejecting, etc. create a new instance of the Cdrom object, passing it the number of the drive starting with 0 .. CD_NUM_DRIVES - 1: $cdrom = new SDL::Cdrom 0; The function CD_NUM_DRIVES will return the number of accessible drives your system currently has. Once open, you can get the device name of the drive using the method name: $name = $cdrom->name(); Polling Status -------------- The method $cdrom->status() differs from the SDL function SDL_CDStatus in that it returns a string describing the status. This method returns the following values: playing stopped paused empty error This was done simply to make it easier to present this information to the end user, in particular programmers debugging their scripts, with little loss of speed. Using the CD ------------ $cdrom->play(track,number_of_tracks,[frame],[number_of_frames]); $cdrom->pause(); $cdrom->resume(); $cdrom->stop(); $cdrom->eject(); The only tricky thing here is that those familiar with the function SDL_CDPlayTracks should be aware that ntracks and start_frame have been swapped to make it easier to use, with the frame oriented parameters being optional. Track Data ---------- To get information on a particular track the method: $cdrom->track(index); will return a hash containing: -id, the track number as one would see on their cd player, -type, the type of data, -length, size of track in frames, -offset, the posistion on the CD. $cdrom->current(); returns the hash for the current track, and $cdrom->current_frame will give you the current frame within that track. $cdrom->num_tracks(); logically, returns the number of tracks on the cd, and $cdrom->id(); returns the id of the cdrom. AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::Mixer(3) SDL::App(3).  File: pm.info, Node: SDL/Cursor, Next: SDL/Event, Prev: SDL/Cdrom, Up: Module List a SDL perl extension ******************** NAME ==== SDL::Cursor - a SDL perl extension SYNOPSIS ======== $cursor = new SDL::Cursor -data => new SDL::Surface "cursor.png", -mask => new SDL::Surface "mask.png", -x => 0, -y => 0; DESCRIPTION =========== To create a new cursor, create a new instance of the Cursor class passing it two surfaces as shown in the example. The x and y values indicate the position of the hot-spot for clicking. To move the cursor to a position on the screen use the warp method passing the values of x and y. The warp function does not require an instance to have been created, and can be safely used directly. SDL::Cursor::warp(x,y); $cursor->warp(200,200); Similary, to toggle the visible status of the cursor use the show method: SDL::Cursor::show(0); # this hides the cursor $cursor->show(1); # make the cursor visible If you have created a new Cursor, to set it as the active cursor use the method 'use': $cursor->use(); Finally, if you are using more than one instance of a SDL_Cursor *, you may find the get method useful for finding out the current cursor. SDL::Cursor::get(); $cursor->get(); NB: This will not return the value of that instance, but rather the instance currently in use; AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::Surface(3).  File: pm.info, Node: SDL/Event, Next: SDL/Font, Prev: SDL/Cursor, Up: Module List a SDL perl extension ******************** NAME ==== SDL::Event - a SDL perl extension SYNOPSIS ======== $event = new SDL::Event; DESCRIPTION =========== SDL::Event->new(); creates a SDL_Event structure, into which events may be stored. $event->type() This function returns the event type which will be one of the values: SDL_ACTIVEEVENT, SDL_KEYDOWN, SDL_KEYUP, SDL_MOUSEMOTION, SDL_MOUSEBUTTONDOWN, SDL_MOUSEBUTTONUP, SDL_QUIT,SDL_SYSWMEVENT. Gathering Events ---------------- $event->poll(); $event->pump(); $event->wait(); These three methods can be used to gather new events. Poll and pump should be used together. Pump will collect events, and poll will read events from the stack, returning 0 if no events were found. Similarly wait will wait for an event to occur, and then return. Active Events ------------- These events indicate a change in the state of the application. The methods which access the event's properties are: $event->gain(); $event->state(); The possible states that an event may return are: SDL_APPMOUSEFOCUS, SDL_APPINPUTFOCUS, and SDL_APPACTIVE. Key Events ---------- Everytime a key is pressed or release, while the app has input focus, a key event will be generated. The following methods provide access to the event's fileds: $event->key_state(); $event->key_name(); $event->key_sym(); $event->key_mod(); $event->key_unicode(); $event->key_scancode(); Key_state will return either SDL_PRESSED or SDL_RELEASED. Key_name will return a string giving the name of the key. Sym will return the SDL key symbol code, which can be checked against the SDLK_* entries as specified in the SDL documentation. (ie sym 27 is SDLK_ESCAPE). Likewise, key_mod will return the current modifier state of the key and can be or'ed against the KMOD_* masks as per the SDL documentation. To enable unicode support, one must first call $event->set_unicode(1); there after each event will fill out the unicode field. The key_unicode function returns the integer of the unicode key. Similarly, key_scancode will return the raw scancode from the key event. Mouse Events ------------ There are two types of mouse related events, motion and button. The exact type is important as there are separate methodss for reading from each. For motion events one should use: $event->motion_state(); $event->motion_x(); $event->motion_y(); $event->motion_xrel(); $event->motion_yrel(); For button events the following are applicable: $event->button_state(); $event->button_x(); $event->button_y(); $event->button(); Button_state will either be SDL_PRESSED or SDL_RELEASED, while button will contain the number of the button pressed, 1, 2, 3, etc. Other things ------------ Additionally, you can use the method 'set' to make the SDL ignore or re-enable event types. For example, you can ignore all SDL_SYSWMEVENT events with the command: $event->set(SDL_SYSWMEVENT,SDL_IGNORE); This is highly recommended as you will have to process fewer events this way. You can also enable key repeats using the method: $event->set_key_repeat(delay,interval); It should be noted that there is currently no support for the SYSWMEVENT events in this structure, as these are really best dealt with C level code. This may change in the future. AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::App(3).  File: pm.info, Node: SDL/Font, Next: SDL/Mixer, Prev: SDL/Event, Up: Module List a SDL perl extension ******************** NAME ==== SDL::Font - a SDL perl extension SYNOPSIS ======== $font = new Font "Font.png"; $font->use(); DESCRIPTION =========== SDL::Font provides a mechanism for loading and using SFont style fonts. To create a new font, simply create a new instance of the class Font, passing it the name of the image file that contains the SFont. To use the font, call the use method of the font instance as shown above. Perl will automagically deallocate all of the buffers. You must create and use a font prior to printing on any surface. For further details see the file SFont-README in this distribution. AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::Surface(3)  File: pm.info, Node: SDL/Mixer, Next: SDL/OpenGL, Prev: SDL/Font, Up: Module List a SDL perl extension ******************** NAME ==== SDL::Mixer - a SDL perl extension SYNOPSIS ======== $mixer = new SDL::Mixer -frequency => MIX_DEFAULT_FREQUENCY, -format => MIX_DEFAULT_FORMAT, -channels => MIX_DEFAULT_CHANNELS, -size => 4096; DESCRIPTION =========== This module provides a pseudo object ( it contains no data ), that handles all of the digital audio for the system. It is simply an interface for SDL_mixer. In general, there is no need to pass any flags to the constructor. The default, shown above, provides 8 channels of 16 bit audio at 22050 Hz. and a single channel of music. The flags passable are -frequency ( or for the impatient -rate ), -format, -channels, -size, which specify the sample frequency, byte format, number of channels, and sample size respectively. Frequency can range from 11025 to 44100. Format is one of the following: AUDIO_U8, AUDIO_S8, AUDIO_U16, AUDIO_S16. For those with big endian machines use AUDIO_U16MSB and AUDIO_S16MSB. Channels default to 8, while size goes to 4096, and can range from 512 to 8096. Given you are using perl, a higher latency is probably more realistic. There are two subordinate modules, Sound.pm and Music.pm which handle the actual file access and memory cleanup. Sound objects also have a per file volume control above and beyond the channel's volume setting. It can be set to half volume as follows: my $wavfile = new SDL::Sound "funk.wav"; $wavfile.volume(64); Sound objects can only load .wav files. Music files, however, can load MIDI files such as .mod .s3m .it .xm. Music files, more importantly, through use of Lokisoft's smpeg library, can play MP3 files. This is, of course, the music format of choice. If you need normal CD audio, please use the Cdrom.pm module. Functions --------- $hashref = $mixer->query_spec(); Query_spec returns a has containing the keys -status, -frequency, -format, and -channels. These are the values that are being used by the mixer. If you are adventurous, the SDL::sdlpl::sdl_*_audio_* functions provide low level access the the SDL Audio features. Without C level callback functions these routines are useless though. $mixer->reserve_channels(n); This calls Mix_ReserveChannels and saves n channels for the app. $mixer->allocate_channels(n); If given a number greater than the current number of channels, it will grow the collection of channels to n. If n is lower, then it will free those channels, and remove them. $mixer->group_channel(channel,group) This will add channel to group, which channel and group are both integers. Similarly, $mixer->group_channels(from,to,group) will add channels from 'from' to 'to' to group 'group'. $mixer->group_available(group) will return the next available channel in a group. $mixer->group_count(group) will return the number of channels in a group, and if group = -1 will return the total number of channels. $mixer->group_oldest(group) will return the longest playing sample in the group. $mixer->group_newer(group) will return the most recently played sample of a playing group. $mixer->play_channel(channel,Sound,loops,[ticks]); $mixer->fade_in_channel(channel,Sound,loops,ms,[ticks]); $mixer->fade_out_channel(channel,ms); $mixer->fade_out_group(group,ms); $mixer->channel_expire(channel,ms); $mixer->halt(channel); $mixer->halt_group(group); $mixer->pause(channel); $mixer->resume(channel); $mixer->fading_channel(channel); $mixer->playing(channel); $mixer->paused(channel); Play_channel will play a Sound object 'Sound', on channel 'channel', and loop 'loops' times, for optionally at most 'ticks' ticks. Fade_in_channel works the same, but fades the sample in over ms milliseconds. Fade_out_channel will fade a channel out for ms milliseconds, where as channel_expire will kill it after ms milliseconds. Halt will kill a channel immediately, and halt_group works on an entire group. Pause and resume works as a pair to pause and resume playback of a channel. Fadding_channel, playing, and paused, all return a value if the channel is in that state. There are a number of similar methods for music. They work basically the same way, but as there is only a single music channel, do not require as many args. They are as follows: $mixer->play_music(Music,loops); $mixer->fade_in_music(Music,loops,ms); $mixer->fade_out_music(ms); $mixer->halt_music(); $mixer->pause_music(); $mixer->resume_music(); $mixer->music_paused(); $mixer->playing_music(); $mixer->fading_music(); In addition to those, music also has two additional commands: $mixer->rewind_music(); $mixer->set_music_command("string"); Volume Control -------------- The MIX_MAX_VOLUME is 128. To set the volume of the music use the method: $mixer->music_volume(vol); Similarly the volume of each channel can be set using: $mixer->channel_volume(channel,vol); For .wav files, the volume of the sample itself can be adjusted as mentioned above using the 'volume' method of the Sound object. The mixer will automagically handle all of the mixing for you. AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::Cdrom(3)  File: pm.info, Node: SDL/OpenGL, Next: SDL/OpenGL/App, Prev: SDL/Mixer, Up: Module List a SDL perl extension ******************** NAME ==== SDL::OpenGL - a SDL perl extension SYNOPSIS ======== Provides OpenGL bits to SDL-Perl, please look at the examples. DESCRIPTION =========== Additional Methods ------------------ AUTHOR ====== Wayne Keenan SEE ALSO ======== perl(1) SDL::Surface(3) SDL::Mixer(3) SDL::Event(3) SDL::Cdrom(3).  File: pm.info, Node: SDL/OpenGL/App, Next: SDL/Rect, Prev: SDL/OpenGL, Up: Module List Glut like wrapper for SDL OpenGL apps ************************************* NAME ==== SDL::OpenGL::App - Glut like wrapper for SDL OpenGL apps SYNOPSIS ======== use SDL::OpenGL::App; my $app=new SDL::OpenGL::App; $app->app_name("Gears"); $app->register_handler(init => \&init, draw => \&draw, events => \&events, idle => \&idle, reshape => \&reshape, ); $app->run(); DESCRIPTION =========== METHODS ======= new add_startup_parameter add_runtime_help register_handler pointer_show run pump screendump app_name screen_width screen_height fullscreen fps glinfo red_size green_size blue_size depth_size doublebufer Package utility methods: read_texture rle_enc rle_dec =head1 EXAMPLES QUICK DEMO/TEST --------------- Running the in-built demo/test: run perl with the 'e' flag to execute these one liners: 'use SDL::OpenGL::App; new SDL::OpenGL::App->run' same, but in fullscreen mode: 'use SDL::OpenGL::App; $g=new SDL::OpenGL::App; $g->fullscreen(1); $g->run' PUMPING ------- 'Pumping' the SDL::OpenGL::App processing loop, step by step: Make use of the 'pump' function, say, when called from a Gtk Idle loop for instance: my $gl_app=new SDL::OpenGL::App ; #register handlers/help as normal my $stay_alive=1; while ($stay_alive) { my $gl_rc=$gl_app->pump(); #returns FALSE when 'reasons to leave' detected $stay_alive=0 unless $gl_rc; } MAKE A MOVIE! ------------- NOTE:: currently (as from V1.06) only RAW PPM files are generated, but then SDL::OpenGL::App can only read ASCII/RAW PPM file anyway, for now. To create a series of screenshots to build a movie, e.g. to build OpenGL looking graphics for a 'flatter' application(s) (game/web/etc..): #do things as usual, then my $frame=0; my $frame_ext_format="%d"; #you may want leading 8 zeros hex, e.g, : "%08x" sub idle { #..do your 'Idle' stuff.. $gl_app->screendump(FILE_NAME=>"movie/gear.".sprintf($frame_ext_format,$frame++)); } to playback the movie, one quick way is to use the 'animate' program from ImageMagick: $ animate movie/gear.* Furthermore, you could then use 'read_texture' to read them all/it back in, to be used as a (possibly animated) bill board, or drop OpenGL mode and then use them in 2D SDL Surfaces, you choose. For more examples please have a look inside the directory: 'examples/openGL/Glut' TODO ==== BUGS ==== AUTHOR ====== Wayne Keenan wayne@metaverse.fsnet.co.uk Copyright (c) 2000 Wayne Keenan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. VERSION ======= Version 0.02 (05 Aug 2000) SEE ALSO ======== perl(1) SDL::App SDL::OpenGL  File: pm.info, Node: SDL/Rect, Next: SDL/Surface, Prev: SDL/OpenGL/App, Up: Module List a SDL perl extension ******************** NAME ==== SDL::Rect - a SDL perl extension SYNOPSIS ======== $rect = new SDL::Rect ( -height => 4, -width => 40 ); DESCRIPTION =========== SDL::Rect->new(...); creates a SDL_Rect structure which is used for specifying regions for filling, blitting, and updating. These objects make it easy to cut and backfill. By default, x, y = 0, and h, w default to 0. (the default scratch sizes); Rect fields ----------- The four fields of a rectangle can be set simply by passing a value to the applicable method. These are: $rect->x(4); # sets x to 4 $rect->y(); # reads y $rect->width(49); # sets width to 49 $rect->height(); # reads height AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::Surface(3)  File: pm.info, Node: SDL/Surface, Next: SDL/sdlpl, Prev: SDL/Rect, Up: Module List a SDL perl extension ******************** NAME ==== SDL::Surface - a SDL perl extension SYNOPSIS ======== use SDL::Surface; $image = new SDL::Surface(-name=>"yomama.jpg"); DESCRIPTION =========== SDL::Surface->new(-name=>"yomama.jpg"); will load an image named yomama.jpg, which works equally well with images of type bmp, ppm, pcx, gif, jpeg, and png. Optionally, if you would like a scratch surface to work with, you can createit using this function using the following syntax: SDL::Surface->new(-flags=>SDL_SWSURFACE,-width=>666,-height=>666,-depth=>8); which will produce a software suface, at 666x666x256 colors. To create an image using the default depth and flag state simply use: SDL::Surface->new(-width=>$my_w,-height=>$my_h); If you are on a big endian machine, or some really funky hardware you can set the RGBA bitmasks with the keys -Rmask, -Gmask, -Bmask, -Amask. For example to create a scratch surface on a big endian machine one would use: SDL::Surface->new(-width=>200,-height=>100, -Rmask=>0xff000000,-Gmask=>0x00ff0000, -Bmask=>0x0000ff00,-Amask=>0x000000ff); DESTROY ------- When a surface is destroyed, perl will call SDL_FreeSurface() on it. Hence don't worry about freeing it yourself. If you must, then invoke the function SDL::sdlpl::sdl_free_surface($your_surface); Read-only Surface fields ------------------------ The SDL_Surface structure has many subfields. Most of these fields are accessible in read-only form. Most of these fields are useless to a perl hacker anyways, and are provided for a sense of completeness. $surface->flags() This field returns the flags which are applicable to the current surface. The possible values for the flags are: SDL_ANYFORMAT SDL_SWSURFACE SDL_HWSURFACE SDL_HWPALETTE SDL_DOUBLEBUF SDL_FULLSCREEN $surface->palette() This field returns a pointer to the SDL_Palette structure for this image if it is an 8 bit image, or NULL if the image is 16, 24, or 32 bit. cf. Palette.pm NB: this should not be passed to any Palette method. what you need there is to create a new Palette object, passing it the image as in: my $pal = new SDL::Palette $image; cf Palette.pm for details. $surface->bpp() This field returns the bits per pixel, aka depth, of the surface. $surface->bytes_per_pixel() This field returns the bytes per pixel, this should in all cases be the same as bpp/8. Technically, it reads that field of the SDL_PixelFormat structure for the surface. $surface->Rshift(); $surface->Gshift(); ... These functions return the Rshift, Gshift, Bshift, and Ashift respectively for the surface. To be perfectly honest, these are not all that useful from perl, but are provided for future expansion. $surface->Rmask(), $surface->Gmask() ... Like Rshift & friends, Rmask, Gmask, Bmask, and Amask return the current byte masks for each component of RGBA surfaces. They are provided for future expansion. $surface->color_key(); This returns the pixel value which was set using $surface->set_color_key(flag,pixel); This is the transparent color for the image. $surface->alpha(); This returns the alpha value of the surface, usually set by $surface->set_alpha(flag,alpha); Alpha values are not applicable to palettized images. $surface->width(); This returns the width of the surface. $surface->height(); This returns the height of the surface. $surface->clip_minx ... clip_miny ... clip_maxx ... clip_maxy clip_minx, clip_miny, clip_maxx, and clip_maxy return the current clipping values for the surface. $surface->pitch(); This returns the pitch of the image, aka the width of a single row of pixels in bytes. This should be the same as $surface->width()*$surface->bytes_per_pixel(). It is provided for future expansion. Poking Pixels ------------- The swiss-army-chainsaw of pixel manipulation, the method $surface->pixel(x,y,color); can be used to read or set the value of a pixel at the point (x,y). If no color value is passed, it will simply read the value at that point. If a color is passed, it will set the point to that value and then return the value to which it was actually set. For the speed conscious, this function is SLOW. It is not designed for line drawing or other large-scale projects. It is my intention to provide a generic drawing system in the future, and additional low level memory tools, but in the mean time, if you must this cudgel. So just to reiterate: $surface->pixel(12,13); # returns the pixel at (12,13) $surface->pixel(12,13,0xffff); # sets that pixel to 0xffff Filling areas ------------- To fill a larger volume than a single pixel the method: $surface->fill($rect,color); will fill a rectangle with the value of color. With intelligent use of Rect objects one can draw buttons and the like. It is also useful in clearing the screen. Locking, Unlocking, and the like... ----------------------------------- When writing to certain surfaces, notably some SDL_HWSURFACE flaged surfaces, it is necessary to lock the surface before twiddling its bits. To tell if you must do so it is wise to call the function: $suface->lockp(); If it returns non-zero you should then call: $surface->lock(); and after your write call: $surface->unlock(); and everything will be well. Locking and unlocking a surface which doesn't require locking only wastes time, so if you have time to spare, you could just do so by default. Bliting & Updating ------------------ To copy image data from one surface to another, the SDL provides a collection of functions. $surface->update(rect,...); will update any number of Rects of the screen, where as: $surface->flip(); will update the entire screen. $surface->blit($srect,$dest,$drect); will copy the contents contained by $srect of the surface $surface into area specified bye $drect of the surface $dest. Please see the documents for Rect.pm for the creation of $srect and $drect. So may Colors in the world ... ------------------------------ To set the colors in a palettized image, the method: $surface->set_colors($start,...) is provided. It takes 1 or more Color objects, and sets the consecutive palette entries starting at entry $start. Hence to set the first ten palette entires one would use: $my_surface->set_colors(0,$color1,$color2,...$color10); where $color1 ... $color10 were created with Color->new(r,g,b); see Color.pm for details. Transperancy and alpha levels for an image can also be set using the methods: $surface->set_color_key(flag,pixel); and $surface->set_alpha(flag,alpha); where the flags for set_color_key are: SDL_SRCCOLORKEY and SDL_RLEACCEL, and the flags for set_alpha are: SDL_SRCALPHA and SDL_MULACCEL. Clipping -------- To set the clipping rectangle for a source surface the method $surface->clip(top,left,bottom,right); will prevent accidental bliting of material outside of this rectangle. Format Conversion ----------------- Occasionally it will be necessary to manipulate images in a format other than that used by the display, to manage the conversion the method: $surface->display_format(); will produce a new surface in the format used for display. Fonts & Printing ---------------- As of version 1.01, SDLpl now supports SFont style fonts. Before printing, one must create and use a new font as specified in SDL::Font. For example to load a font stored in Ionic.png one would use: $font = new Font "Ionic.png"; $font->use; Then to print a string to (10,13) on a surface one would use the print method of the surface: $surface->print(10,13,"Hello World"); AUTHOR ====== David J. Goehrig SEE ALSO ======== perl(1) SDL::Rect(3) SDL::Font(3).  File: pm.info, Node: SDL/sdlpl, Next: SETI/Stats, Prev: SDL/Surface, Up: Module List Perl bindings for the SDL ************************* NAME ==== SDL::sdlpl - Perl bindings for the SDL SYNOPSIS ======== use SDL::sdlpl; DESCRIPTION =========== sdlpl is a collection of bindings for functions in the Simple DirectMedia Layer, and an assortment of related utilities. The module sdlpl is not indended for direct use, but rather serves as the backbone of a collection of Object-Oriented modules which provide access to the SDL library. The associated modules are App.pm, Surface.pm, Event.pm, Rect.pm, Palette.pm, Mixer.pm, Cdrom.pm and OpenGL.pm. AUTHOR ====== David J. Goehrig Wayne Keenan SEE ALSO ======== perl(1) App(3) Surface(3) Event(3) Rect(3) Palette(3) Mixer(3) Cdrom(3) OpenGL(3) OpenGL::App(3)  File: pm.info, Node: SETI/Stats, Next: SGI/FAM, Prev: SDL/sdlpl, Up: Module List gather local and remote SETI@home stats and manipulate them *********************************************************** NAME ==== SETI::Stats - gather local and remote SETI@home stats and manipulate them SYNOPSIS ======== use SETI::Stats; $s = new SETI::Stats ( rsh => "/semi-free/bin/ssh -l ernie", host => "bert", dir => "/seti" ); $s->visit; print $s->user_info("email_addr"); print $s->bar . "\n"; $t = new SETI::Stats ( dir => "/martin/seti", save => "p" ); while (1) { $t->visit; print $t->dump . "\n\n"; sleep(60); } DESCRIPTION =========== This Perl class provides an object oriented API which lets you gather SETI@home stats from one or more machines and gives you a programmatic way of getting access to them. It can cope with multiple SETI@home clients which share a directory hierarchy accessible to the machine it is run on, clients which each have their own private filespace (using rsh, ssh or equivalent) and even works for boxes running Windows NT. SETI::Stats borrows from Jan Rocho's *perlseti.pl*, but differs in several ways - this is a module devoted to stats gathering rather than a general purpose control program, it can be used to monitor remote machines without even requiring Perl to be installed on them, and it provides a generic framework for access to (both local and remote) SETI@home client stats. It could also be extended to cover stats gathering from the SETI@home WWW server, though this may be better done in a separate module to avoid code bloat. METHODS ======= Each *SETI::Stats* object supports the following methods: new Create a new *SETI::Stats* object. The following parameters are supported: dir This is the (local or remote) directory where *SETI::Stats* will look for the SETI@home client's stats files. It defaults to */home/seti*. host When gathering stats remotely, this is the name of the host to contact. It will also be used as part of the name of *SETI::Stats*' own state file - see below for more info on this. rsh The command (rsh or equivalent) which will be used to contact the remote host when gathering stats over the Internet. If you need to specify a user name or other parameters, you can add them here, e.g. rsh => "/semi-free/bin/ssh -l ernie" This defaults to ssh. save The filename (absolute or relative) prefix of the local file to store *SETI::Stats*' state info in. This defaults to perlseti_data. See below for more information on state file naming. source The radio telescope data source for the SETI@home client. By default this is set to the *Arecibo Radio Observatory*, which is currently the only source of data for the SETI@home experiment. Note that none of these parameters is mandatory. In particular, you don't have to store state info between polling clients - unless you want to use the dump method. The visit method will store it for you, however! poll This method polls the SETI@home client being monitored by this *SETI::Stats* object for a given section of its stats. It takes the following parameters: checkpoint This indicates that the poll invocation is of the local checkpoint file maintained by *SETI::Stats* rather than a (possibly remote) state file maintained by the SETI@home client itself. It's set automatically by the visit method when updating the local checkpoint file. section This is the section name to poll for, corresponding to the file section.txt in the SETI@home working directory on the client machine. This method is normally used internally by the visit method. populate This method populates the internal data structures used by *SETI::Stats* for this section of the stats. It takes the following parameters: results An array of results, in the format *attribute*=value, with one attribute/value pair per entry - e.g. *prog=0.487688* section The section name of the stats to populate, e.g. work_unit. This method is normally used internally by the visit method. checkpoint This method saves *SETI::Stats*' current state info to a file on the local machine (even when monitoring a remote one). The file name is determined by the values of the dir and save parameters when the object was created, e.g. with a dir of */seti* and a save of *perlseti_state*, the file created would be */seti/perlseti_state.txt* when the local host was being monitored. In the case of a remote client being monitored, the host name is appended to dir and save, prefixed by an underscore, e.g. for the client machine *bert*, the file would be */seti/perlseti_state_bert.txt*. Note that the value of save no longer needs to contain the string *perlseti* (as was the case in *SETI::Stats* 1.00 and 1.01) for this feature to work properly. You don't have to checkpoint, but be aware that this info is used by the dump method. This method is normally used internally by the visit method. visit This method is the one you would normally call when polling a given SETI@home client for its stats. It in turn calls the poll method for each of the result_header, state, user_info, version and work_unit stats files and populates the *SETI::Stats* object's internal data structures with the contents of these files. These are then accessible through the result_header, state, user_info, version and work_unit methods. visit also calls the checkpoint and poll methods, which store *SETI::Stats*' state information and populates the internal data structure used by the perlseti_data method. Access methods: bar Returns a progress bar of '#' characters, representing the percentage of the work unit which has been analysed so far - on a scale of 0 to 80 characters, where 80 indicates that the work unit is complete. dump Returns a SETI stats info 'screen' in the style of *perlseti.pl*, based on the last polled values for this SET@home client. perlseti_data The method returns the value of the nominated parameter in the perlseti_data section of the client's stats. This section is unusual in that it is collected by *SETI::Stats* rather than the SETI@home client itself. result_header This method returns the value of the nominated parameter in the result_header section of the client's stats. state This method returns the value of the nominated parameter in the state section of the client's stats. user_info This method returns the value of the nominated parameter in the user_info section of the client's stats. version This method returns the value of the nominated parameter in the version section of the client's stats. work_unit This method returns the value of the nominated parameter in the work_unit section of the client's stats. Examples of the access methods in use can be found above in the SYNOPSIS section of this manpage. BUGS ==== This is still fairly new stuff, so probably contains much which is apocryphal, or just plain wrong :-) If the object existed already we should probably take care to overwrite or remove old stats in a section when doing an update, or we could end up with the situation that some stats are current but others aren't. Return codes should be documented. There should be a test module. Debugging options would be useful! COPYRIGHT ========= Copyright (c) 1999, Martin Hamilton . All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Martin Hamilton  File: pm.info, Node: SGI/FAM, Next: SGML/Element, Prev: SETI/Stats, Up: Module List Perl interface to SGI/Irix File Access Monitor ********************************************** NAME ==== *SGI::FAM* - Perl interface to SGI/Irix File Access Monitor SYNOPSIS ======== use SGI::FAM; my $fam=new SGI::FAM; $fam->monitor('/foo'); $fam->monitor('/foo/bar.txt'); while (1) { my $event=$fam->next_event; # Blocks print "Pathname: ", $event->filename, " Event: ", $event->type, "\n"; } Asynchronous mode: while ($fam->pending) { my $event=$fam->next_event; # Immediate ... } # Do something else DESCRIPTION =========== Provides a somewhat higher-level and friendlier interface to the SGI/Irix File Access Monitor API. This allows one to monitor both local and remote (NFS-mounted) files and directories for common filesystem events. To do so, you must register "monitors" on specified pathnames and wait for events to arrive pertaining to them. To get a full description of the API, you should see `fam(3x)' in this node. Since FAM only deals with absolute pathnames, all paths are canonicalized internally and monitors are held on canonical paths. Whenever a path is returned from this module, howvever, via which or *monitored* with no arguments, the originally specified path is given for convenience. MAIN METHODS ============ new [ *appname* ] ----------------- Create a new FAM connection. An application name may be given. pending ------- True if there is an event waiting. Returns immediately. *debug_level* [ level ] ----------------------- Set or query debug level. Values are *FAM_DEBUG_OFF*, *FAM_DEBUG_ON*, and *FAM_DEBUG_VERBOSE* (you should ask to import these). next_event ---------- Returns next event in queue, as an event object. Blocks if necessary until one is available. *monitor* path [ unique [ type [ depth mask ] ] ] ------------------------------------------------- Monitor the specified file or directory. Expect a slew of events immediately (*exist* and *end_exist*) which may not interest you. unique, if specified and true, will produce a warning if the monitored path is not unique among those already being monitored. This can be helpful for debugging, but normally this is harmless. type may be file, dir or *coll*; it defaults to file or dir according to an *existing* filesystem entry. If you specify *coll* (collection), pass additional depth and mask arguments, if you ever figure out what that does (SGI does not say). *cancel* path ------------- Stop monitoring this path. *monitored* [ path ] -------------------- List all currently monitored paths, or check if a specific one is being monitored. Does not check if a monitor is suspended. *suspended* path ---------------- True if the specified monitor is suspended. *suspend* [ path ] ------------------ Suspend monitoring of a path, or all paths if unspecified. resume [ path ] --------------- Resume monitoring of a path, or all paths if unspecified. which event ----------- Gives the pathname for the monitor generating this event. Often this will be the same as `$event->filename', but will differ in some cases, e.g. in create events where filename will yield the basename of the new file while the which method must be invoked to determine the directory of creation, if more than one is being monitored. EVENT METHODS ============= hostname -------- Host of event. Does not seem to work, actually. filename -------- Path of event, according to FAM. type ---- Type of event; one of the following strings: change, delete, *start_exec*, *stop_exec*, create, move, ack, *exist*, *end_exist*. BUGS ==== Most of these can be observed with `monitor'. Hostnames Do not seem to be supplied at all. Timing Is somewhat erratic. For example, creating a file that had been monitored and deleted will signal a create event on it, after about a second pause. Execute Events Are not sent, as far as the author can determine. SEE ALSO ======== For the raw SGI interface (rather poorly documented), see `fam(3x)' in this node. AUTHORS ======= J. Glick *jglick@sig.bsh.com*. REVISION ======== X<$Format: "`$Source$' last modified $Date$ release $ProjectRelease$. $Copyright$"$> `lib/SGI/FAM.pm' last modified Thu, 25 Sep 1997 22:56:42 -0400 release 1.002. Copyright (c) 1997 Strategic Interactive Group. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  File: pm.info, Node: SGML/Element, Next: SGML/Entity, Prev: SGI/FAM, Up: Module List an element of an SGML, XML, or HTML document ******************************************** NAME ==== SGML::Element - an element of an SGML, XML, or HTML document SYNOPSIS ======== $element->gi; $element->name; $element->attr ($attr[, $value]); $element->attr_as_string ($attr[, $context, ...]); $element->attributes [($attributes)]; $element->contents [($contents)]; $element->as_string([$context, ...]); $element->iter; $element->accept($visitor, ...); $element->accept_gi($visitor, ...); $element->children_accept($visitor, ...); $element->children_accept_gi($visitor, ...); DESCRIPTION =========== An `SGML::Element' represents an element in an SGML or XML document. An Element contains a generic identifier, or name, for the element, the elements attributes and the ordered contents of the element. `$element->gi' and `$element->name' are synonyms, they return the generic identifier of the element. `$element->attr' returns the value of an attribute, if a second argument is given then that value is assigned to the attribute and returned. The value of an attribute may be an array of scalar or `SGML::SData' objects, an `SGML::Notation', or an array of `SGML::Entity' or `SGML::ExtEntity' objects. attr returns undef for implied attributes. `$element->attr_as_string' returns the value of an attribute as a string, possibly modified by `$context'. (XXX undefined results if the attribute is not cdata/sdata.) `$element->attributes' returns a reference to a hash containing the attributes of the element, or undef if there are no attributes defined for for this element. The keys of the hash are the attribute names and the values are as defined above. `$element->attributes($attributes)' assigns the attributes from the hash `$attributes'. No hash entries are made for implied attributes. `$element->contents' returns a reference to an array containing the children of the element. The contents of the element may contain other elements, scalars, `SGML::SData', `SGML::PI', `SGML::Entity', `SGML::ExtEntity', or `SGML::SubDocEntity' objects. `$element->contents($contents)' assigns the contents from the array $contents. `$element->as_string' returns the entire hierarchy of this element as a string, possibly modified by `$context'. See *Note SGML/SData: SGML/SData, and *Note SGML/PI: SGML/PI, for more detail. (XXX does not expand entities.) `$element->iter' returns an iterator for the element, see `Class::Visitor' for details. `$element->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_Element($element[, ...])'. See examples `visitor.pl' and `simple-dump.pl' for more information. `$element->accept_gi($visitor[, ...])' issues a call back to `$visitor->visit_gi_*GI*($element[, ...])' where *GI* is the generic identifier of this element. `accept_gi' maps strange characters in the GI to underscore (`_') [XXX more specific]. `children_accept' and `children_accept_gi' call accept and `accept_gi', respectively, on each object in the element's content. Element handles scalars internally for as_string, `children_accept', and `children_accept_gi'. For `children_accept' and `children_accept_gi' (both), Element calls back with `$visitor->visit_scalar($scalar[, ...])'. For as_string, Element will use the string unless `$context->{cdata_mapper}' is defined, in which case it returns the result of calling the `cdata_mapper' subroutine with the scalar and the remaining arguments. The actual implementation is: &{$context->{cdata_mapper}} ($scalar, @_); AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::SData(3), SGML::PI(3), Class::Visitor(3).  File: pm.info, Node: SGML/Entity, Next: SGML/ExtEntity, Prev: SGML/Element, Up: Module List an entity defined in an SGML or XML document ******************************************** NAME ==== SGML::Entity - an entity defined in an SGML or XML document SYNOPSIS ======== $name = $entity->name; $data = $entity->data; $entity->iter; $entity->accept($visitor, ...); The following are defined for type compatibilty: $entity->as_string([$context, ...]); $entity->accept_gi($visitor, ...); $entity->children_accept($visitor, ...); $entity->children_accept_gi($visitor, ...); DESCRIPTION =========== An `SGML::Entity' contains an entity defined in a document instance. Within a grove, any entity with the same name refers to the same `SGML::Entity' object. `SGML::Entity' objects occur in a value of an element attribute or as children of entities. `$entity->name' returns the name of the Entity object. `$entity->data' returns the data of the Entity object. `$entity->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_Entity($entity[, ...])'. See examples `visitor.pl' and `simple-dump.pl' for more information. `$entity->as_string' returns an empty string. `$entity->accept_gi($visitor[, ...])' is implemented as a synonym for accept. `children_accept' and `children_accept_gi' do nothing. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::Element(3), SGML::PI(3).  File: pm.info, Node: SGML/ExtEntity, Next: SGML/Grove, Prev: SGML/Entity, Up: Module List an external entity defined in an SGML or XML document ***************************************************** NAME ==== SGML::ExtEntity - an external entity defined in an SGML or XML document SYNOPSIS ======== $name = $ext_entity->name; $data = $ext_entity->data; $type = $ext_entity->type; $system_id = $ext_entity->system_id; $public_id = $ext_entity->public_id; $generated_id = $ext_entity->generated_id; $attributes = $ext_entity->attributes; $notation = $ext_entity->notation; $ext_entity->iter; $ext_entity->accept($visitor, ...); The following are defined for type compatibilty: $ext_entity->as_string([$context, ...]); $ext_entity->accept_gi($visitor, ...); $ext_entity->children_accept($visitor, ...); $ext_entity->children_accept_gi($visitor, ...); DESCRIPTION =========== An `SGML::ExtEntity' contains an external entity defined in a document instance. Within a grove, any entity with the same name refers to the same `SGML::ExtEntity' object. `$ext_entity->name' returns the name of the external entity object. `$ext_entity->data' returns the data of the entity if it has been loaded (XXX but that's not been defined yet). `$ext_entity->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_ExtEntity($ext_entity[, ...])'. See examples `visitor.pl' and `simple-dump.pl' for more information. `$ext_entity->as_string' returns an empty string. `$ext_entity->accept_gi($visitor[, ...])' is implemented as a synonym for accept. `children_accept' and `children_accept_gi' do nothing. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), SGML::Grove(3), Text::EntityMap(3), SGML::Element(3), SGML::PI(3).  File: pm.info, Node: SGML/Grove, Next: SGML/Notation, Prev: SGML/ExtEntity, Up: Module List an SGML, XML, or HTML document ****************************** NAME ==== SGML::Grove - an SGML, XML, or HTML document SYNOPSIS ======== use SGML::Grove; $grove = A::GroveBuilder->new ($sysid); $root = $grove->root; $errors = $grove->errors; $entities = $grove->entities; $notations = $grove->notations; $grove->as_string([$context, ...]); $grove->iter; $grove->accept($visitor, ...); $grove->accept_gi($visitor, ...); $grove->children_accept($visitor, ...); $grove->children_accept_gi($visitor, ...); DESCRIPTION =========== `SGML::Grove' represents a loaded document instance returned from a grove building or parsing module, i.e. for SGML documents this may be SGML::SPGroveBuilder. The returned grove contains the root, or top, element of the document and an array of any warnings or errors that may have been generated while parsing the document. `$grove->root' returns the `SGML::Element' of the outermost element of the document. `$grove->errors' returns a reference to an array containing any errors generated while parsing the document. `$grove->entities' returns a reference to a hash containing any entities referenced in this grove (as opposed to entities that may have been declared but not used). `$grove->notations' returns a reference to an array containing any notations referenced in this grove. `$grove->as_string' returns the entire grove as a string, possibly modified by `$context'. See *Note SGML/SData: SGML/SData, and *Note SGML/PI: SGML/PI, for more detail. `$grove-'iter> returns an iterator for the grove object, see `Class::Visitor' for details. `$grove->accept($visitor[, ...])' issues a call back to `$visitor->visit_SGML_Grove($element[, ...])'. See examples `visitor.pl' and `simple-dump.pl' for more information. `$grove->accept_gi($visitor[, ...])' is implemented as a synonym for accept. `children_accept' and `children_accept_gi' call accept and `accept_gi', respectively, on the root element. AUTHOR ====== Ken MacLeod, ken@bitsko.slc.ut.us SEE ALSO ======== perl(1), Text::EntityMap(3), SGML::Element(3), SGML::SData(3), SGML::PI(3), Class::Visitor(3).