Ruby API Reference

Is there any way to draw into an Image? I can do this using RMagick and then create a new Gosu::Image but this is a very costly operation.

I see that it's costly, but implementing a drawing interface for Gosu::Image would be very much work considering the RMagick route is sufficient for most tasks. Could you describe what you are trying to implement? Because there are some optimizations being tested in my secret lab and they may help.

I was trying to add a paint tool so that users could create their own shapes from within the program. Any ideas would be appreciated. All I really need are lines with variable thicknesses (and colours of course).

Is this is it for the documentation? Is there an Rdoc setup somewhere? It seems light, which I suppose is a good thing, but it almost feels too light.

netghost, that's on the ToDo, but not where it would be covered in 2007. Do you need it urgently? I know someone else who would happily use it if it was there, so I could move it to the front.

rabbitblue, I took a look at rdoc years ago, and back then it was not feasible to generate Rdoc from the C++ sources. I guess the situation is better now, but I just don't have enough time to port it all. Contributions and advice for later are very welcome. So far I've concentrated on example games, because many people asked for inspiration about how to turn a Window and a bunch of 'draw' calls into a game; I tried to answer that first before going into detail about how the functions behave.

rsheehan, hm, that is already something that would need a lot of work and interface design to get right if it would work directly with Images :( I don't know in what context you're trying to do this, but if you can work around it by splitting the image up (= cheap recreation) or working with draw_line and just creating a new RMagick image when a small lag won't be noticed, that would probably be easier ;)

That's a fair answer regarding Rdoc.

The Captain Ruby example was awesome! I loaded it up for the first time last night and was amazed you got so much functionality in so little code. I dig the tiling idea, too -- very slick. Keep up the good work...

I just tried to use an overly large z position when drawing an image; I figured out the legal range from the source, but maybe there should be a brief mention of ZPos here?

The Z-pos range has been changed to cover the whole 'double' range in Gosu 0.7.7 (which will be out for Linux too, in a minute).

I have a quick question regarding Input module button IDs. What is the button ID corresponding to alphabetic keys? I apologize if this is answered elsewhere, but in a quick scan of several source listings and the wiki, I can't seem to find an example or answer. Thanks for any help.

After rereading my previoius post, I suppose I should clarify. Are there convenient aliases like Button::KbNumeric0? for alphabetic keys? I've simply used Window::char_to_button_ID() to map the keys I needed for my current code, but I figured there might be another solution. Thanks again!

No, there's no other way yet. This is because Gosu button indices are currently scancodes for the input API used on each platform, and the code for Z (and other keys) may change due to different keyboard layouts. It is very possible that this will change, maybe with the new Input design I plan to include in 0.8.0.

BTW, the Button module is deprecated for consistency with the C++ version, just use Gosu::KbNumpad0? :) It will still continue to exist until other code-breaking changes are introduced, though.

That makes sense. I did write a small method within the Window class to generate the constants I was using that might be helpful to others:

  def init_keyboard_constants()
    %w{a b c d e f g h i j k l m n o p q r s t u v w x y z}.each do |letter|
      eval "Gosu::Kb#{letter.upcase} = #{self.char_to_button_id(letter)}"
    end
  end

Once called from Window::initialize, key constants like Gosu::KbD exist. Thanks for the great work. I've really enjoyed playing around with the library.

@Nicholas: Half offtopic, to make it shorter you could replace

%w{a b c d e f g h i j k l m n o p q r s t u v w x y z}

by

('a'..'z')

Since this gave a friend and me a bit of a headache to figure out, I thought I'd make a note of it here. Just understand that we don't have a strong background in game dev or graphics, so be kind if you think this was obvious.

Anyway, the description of Image::load_tiles is slightly unhelpful, when trying to understand what the function does. Maybe just a quick one-liner about what is meant by a "tile?" Just a thought.

(Sorry for the long delay, I'm slowly crunching through my e-mail notifications after a busy month :))

I will feature-freeze Gosu once the hopefully rock-solid 0.7.9 is out (still working on the only new feature, TextInput?), then spend some time on unifying and extending the documentation. I hope this will make it easier to get started! Thanks for the feedback.

Thanks for the great framework, having fun so far!

Question: is there a way to return the ID of the current button being pressed? (As opposed to only being able to test for known IDs with button_down?(id) )

nefigah: Sure, overwrite the button_down method (without question mark). :)

Wow, yes, I'm an idiot :x Thanks!

How does one use the playing? method for Sample? I see the SampleInstance? class, but don't understand how to interact with it.

Also, the volume method for Song doesn't seem to work. At least on my machine. OS X Leopard, gosu (0.7.9.1).

rabbitblue: Example: instance = @my_sample.play; puts "What a long sound!" while instance.playing?

And I'll file a bug for the volume method. Seems some Linux sound bugs have just been reported too, so its in good company (sigh). :)

Ah, I see. Sweet beans.

Are there reasons to not use the Sample class to play music? If not I can use Sample because the volume works there.

Samples take longer to load, and keeping a realistic game's soundtrack in memory all the time seems wasteful. But actually, I don't think it should be a problem with current Gosu games in any case. Of course, Song also supports formats not supported by Sample, like .xm or .s3m, but I haven't seen any of them for a long time :(

Anyway, Song#volume isn't there because it takes some lines of code to implement, and I thought I'd wait until someone asks. Seems now is the time to fill the (weird) gap :)

how can i rewrite the close method within the GOSU::Window class... im using ruby and i attempted so simply do as such: class Gosu

class Window

def close

1. o code

end

end

but it didnt change anything... i NEED it to free a dll library on exit or it will crash the computer... please help if possible

Hi, it's module Gosu, not class Gosu! But I think it will NOT be called e.g. the user closes the window with the mouse. What kind of library is it? Does it depend on the window being open? If you need the library to be freed before the window is freed, you can try defining a finalizer for the window. I haven't done that before though. Good luck and let us know if it works :)

basically its an udio library but it uses: LoadLibrary? = Win32API.new('kernel32','LoadLibrary?',['p'],'l') to load the library and: FreeLibrary? = Win32API.new('kernel32','FreeLibrary?',['p'],'l') to free the library... the free and other things need to be called on exit (the library is opened with loadlibrary and then contexts are created from it... you must then free the library and destroy the contexts as the system exits). im not sure what else to do XD

also how do you make a 'finalizer'?

also if you want i can help create new code for ruby/gosu... ive developed my own audio system running off of my own library (the reason for the problems above XD) and my own keyboard module which uses ruby code and as such can be edited... its up to you

As I said I haven't used finalizers, I guess Google is your friend here ;) Also, you should be able to put code after yourwindow.run on all systems that will be called after the Window has closed (but you can't rely on it still being open at that point if you need the HWND to still be valid.

another quick qustion... i didnt find any information that was completely explanatory on the idea but can ruby/gosu be used for commercial games and if so what must be given (credits and reference blablabla)... also i know Fmod cant be used commercially but as i said ive rebuilt the audio functions and ive got them to work on ruby/gosu now anyway

No problem, the only thing you can't do with Gosu is claim you've written it yourself.

awesome... is there anywhere to post submitted edits and such to the system as im using ruby itself to recreate some of the ruby/gosu functions (as no offence but the audio system is a bit limited and i want it to run off my own commercially intended dll anyway... same with keyboard input except thats from windows dlls).

another thing... with a system im making for new inputs and window functionality i would need to know the processed name for the window once opened (as im using the FindWindowEX function within user32.dll) this way its more secure than using the ActiveWindow? function

For showing what you built using Gosu, extensions included, the GosuUsers page is the only official place for now. If that ever changes, I will also move all postings there to the new place, so nothing will be lost ;)

The window class name for Gosu::Window is, tada, "Gosu::Window". :) I don't think that'll ever change, so feel free to use that. If you want to avoid messing with other open Gosu windows (you never know what people run in the background) you should of course combine that with setting/checking the title bar.

yer... i was aiming to do that but i needed the process / handle name first XD

thanks and im gonna check out the GosuUsers page now XD

this is really strange... ive been working on my audio system on rpgmaker xp (dont laugh... i dont use it anymore) and on ruby/gosu on a vista computer... but now im working on my xp its broken... the system should return a handle to a music stream from my dll but it doesnt... as i said this works on rpgmaker xp on both vista and xp and ruby / rubygosu on vista... but it doesnt work on base ruby OR ruby / gosu on xp... if possible could you take a look at the system and tell me whats wrong

I don't know the Win32 libraries, so I can't really help beside the usual advice to put a lot of logging into it…

yer... it was a problem within the library itself which is nbow fixed (it wasnt initializing the COM port so streams werent being created in ruby... but as its fixed ive got my audio system back on track to expect my edited gosu engine to come out sooner than later (it will include a better audio system and what i believe to be a better input system too... but then again its coded in ruby and within the engine so it might not be all that great to some people)

also if you like some of the features i have no problem with you integrating them within the gosu.so file as it would make it easier anyway... overall its just a system that im using for my personal games but if people want them they can have it too... its simple enough... but for ruby only

ha C++

ghey... there isnt a dump function in your image class...

would you be able to add such a thing... i got one half complete but on ruby it spackers when trying to move the bitmap memory data from the system into a file... i have actually got the data layout sorted though...

oh well..

You can easily write a dump function using the OpenGL functions, that will only work for images that fit on one texture though. What would you use it for?

encrypted images in a single patchable file... it allows me to keep the images safe from easy copying and also allows me to patch them into that file easier... if you know a specific way (taking into mind im using ruby) then would you be able to share / help?

how do i draw things like circles and lines?

jrmair, for lines there is the Window#draw_line method. You can either draw circles by calling draw_line in a loop and using offset_x/offset_y or sin/cos, or by using an image that stores a circle. Gosu only provides what is available on the hardware here.

just a quick question... will you ever be adding something like... a viewport? basically a variable given at the images draw function that shows only part of the image (e.g. 12 horizontal pixels out of 30 horizontal pixels) (it might already be done but i cant see how or where it is)...

second whats up with the [srcX, srcY, srcWidth, srcHeight] in: initialize(window, filename_or_rmagick_image, hard_borders, [srcX, srcY, srcWidth, srcHeight]) - Gosu::Image?

i dont know how to use it or what it does as it errors when i attempt to use any digit / nil with it (Gosu::Image.new(self,'test.png',false,[1,1,1,1]) <- this errors... and i dont know what it does or why...)

sorry for the extensive questions... i just always go further than neccessary and im not the best at ruby yet XD... bad combination i guess

Hi, first question: There is no viewport and if there were, it would probably work the other way around (i.e. as a clipping rectangle on the destination surface). Second question: The square brackets mark optional arguments, as I was used to this syntax from the MSDN and other sources. I see that t hey're a bit ambiguous for Ruby documentation. Just omit them and your example will work.

so its impossible to use those extra arguments? (as if im reading it right it supposed to allow you to clip the image into a location on initialization or something like that)

i know how to reate an image (by omitting those last 4 arguments) but i want to know if i can actually use them and if so how

also i guess that the viewport wouldnt be all that necessary...

one other thing... with the Gosu::Image.load_tiles would it be possible to add an extra argument that allows you to specify how many tiles you want created (e.g. 100 pixel image, Gosu::Image.load_tiles(self,'test.png',10,10,5 <- extra argument) that will create 5 images from it, the first 5

You CAN use the last four arguments. Just don't put them in square brackets. You just cannot change the "viewport" during runtime. And you can only load all tiles or none. If the file isn't too huge, just call Image.load_tiles(...).first(5).

cool... by the way ive added a fade_to function to the draw arguments if you want to see... it does what it says basically, it fades from a colour to another colour in a specified time... its still not perfect and im trying to build it into the standard image system but it should be finished if you want to take a look at it later...

also if you make the last 2 arguments (srcWidth,srcHeight) bigger than the image's standard size it crashes... perhaps its possible to simply make it readjust to its maximum if such happens or just add transparant pixels?

It doesn't crash, learn Exceptions ;) Not sure if that should be changed. I'm usually all for fail-early and I don't know why you would give wrong arguments?

well i was using the RTLMoveMemory function to take the read image buffer and dump it... but it needs to create an image of the same size so i gave a 1*1 pxl placer (just to satisfy the filename argument) and then i tried to make the image the right size (23*15) but it errored... also it doesnt raise and exception for me as i catch all exceptions in: begin

Game.new.show

print error

then again ive only been working on these systems for a little while and ive yet to learn everything about gosu so it may just be my fault (most likely is XD)

Sorry, can't help you with that, moving stuff INTO an image is not going to work anyway. If you want to create a non-hacky-as-hell version of that (:P), just have your class respond to "obj.to_blob { self.format = 'RGBA'; self.depth = 8 }".and pass obj to Image#initialize like you would with an RMagick image.

i didnt understand any of that :'(

would you be able to give a real life example (you can also send me stuff via email - its my name XD - incase you dont want me filling this area up anymore)

Your email address appears truncated to me, but anyway, write a to_blob method that returns image data in the same way the RMagick::Image#to_blob method does when called with format = 'RGBA' and depth = 8. Gosu will call that method on anything that isn't a String when passed as a filename, and take the image data from that. You will have to read the RMagick docs up to see the exact format that the to_blob method generates in that case.

OH... Rmagick has to_blob method... that makes more sense... i dont use Rmagick (yet) so it was confusing as to what the to_blob method was... also my email is mechacrash@hotmail.com

guess its time to look at Rmagick (i hope it can be used commercially)

hello friends. does the Gosu::image#draw method draw from the center of the image or from the top left corner?

Image#draw uses the top left corner.

Image#draw_rot uses the center by default (because it's the only thing that makes sense in 90% of the cases for rotated images). The draw_rot function can use a different rotation center though, via the center_x and center_y arguments.

hello, thanks for your quick response to my last question. Another question, do i have to #stop my Gosu::Song from playing before i #play another one? or does playing another song automatically #stop the previous?

thanks

jrmair: It will automatically stop the old song. The logic is that there is only one song playing at any time.

hey, how can i find the colour of a pixel at a particular x,y location?

also, how do i flip an image (not rotate it) so i can have it facing the other way?

First question, not at all. I wonder if I can add that specific feature without people demanding to turn Gosu into a full-fledged imaging library. At the moment, Gosu Images are just there to be drawn, and you need a different library to do that, e.g. RMagick.

Second question, pass -1 for the factor_x argument.

hey, sorry to bug you again. but i assume there's no way to get access to the image pixel buffer? i need that data to figure out per-pixel collisions for my game. Or if you could suggest another way to do it? (if that functionality is not in gosu). i dont really want to use RMagick, as what im doing is quite simple and i dont want all that bloat and extra functionality for such a simple function.... thx!!

Only way would be to use OpenGL calls, as Image has the tex_info stuff. That will only work for images that fit on a single OpenGL texture though (which is guaranteed for up to 500x500 pixels). Also you wlll have to figure out how to do that :) I will think about adding it in the next version though, since it's been requested a few times in the last weeks.

Hey Julian, should one be able to draw single pixels using draw_line and using the same value for both the beginning x and y and end x and y? I'm trying it now but it doesn't draw anything. If I increase the the end point by + 1 I get a 2px line though.

I can achieve the same effect by using a 1px image, but thought I'd ask.

I would go with the image just to be on the safe side. Lines seem to be highly dependent on the OpenGL implementation and graphics driver, and are generally only okay for drawing, well, lines :)

just a quick question... do RMagick image functions work on Gosu::Image's when they are created with RMagick.

e.g. you create the image with RMagick and init with Gosu::Image.new can you now turn that gosu image into a blob using to_blob or is the functionality lost?

hey in your ref you say "See examples/OpenGLIntegration.rb. " where can i find OpenGlIntegration?.rb ?

If you installed Gosu via Gem, then it's in <rubypath>/lib/ruby/gems/1.8/gems/gosu.../examples. Don't know how I can make that more accessible :(

is there any simple way of checking the fps?

i find that making a variable react to every frame is a little... dodgy

mecha, I just drop this class or some equivalent thereof in my project: http://www.raschke.de/julian/temp/FPSCounter.rb Then just call .register_tick in draw (or update, depending on what you want to measure) and output the result of the .fps method somewhere.

cool... i was just wanting to use it to check how badly my system lags XD

im expecting to lose a couple of frames after all

whats the lag difference between using Rmagick images and standard Gosu images? Is there a big difference or none? (im talking the standard simple load a .png from a file - generally 640*480 size - and display it on screen with default params)

None for using them, for loading them you will have to benchmark it yourself. Please post the results too :)

will do XD

hey, im trying to read in the pixel buffer from an image im using in gosu. you suggested i use the opengl functions, so im doing the following:

@image=Gosu::Image.new(self,"test3.png");
 
info=@image.gl_tex_info; 

glEnable(GL_TEXTURE_2D); 

glBindTexture(GL_TEXTURE_2D, info.tex_name); 

data=glGetTexImage(GL_TEXTURE_2D, 0, GL_RGB, GL_FLOAT); 

texture=data.unpack("f");

... the image im using is only 4x4 pixels...and every pixel is coloured (none black). However when i display the contents of the texture array every element appears to be equal to 0.0, also the array seems to be much larger than necessary for a 4x4 image. This is clearly not right.

How do i get the correct image data back an array using opengl? how are you creating the textures using glTextImage2d() ? what parameters do i send to glGetTexImage() to get the image back? or what am i doing wrong?

thanks in advance...i really need to get this pixel-level stuff working for my gosu game..

john

sorry the above texture=data.. should read:

texture=data.unpack("f*")

thanks

Gosu always creates large quadratic textures and allocates the image data for as many Images as possible on those. Even if it wouldn't do this, it might have to round up the image size to the next power of two (on older chipsets). This is why the GLInfo type has the left, top, right and bottom fields. These are values in the range of 0 to 1 that specify where the relevant image data is located. You can calculate these back into pixel values by assuming that the texture is always quadratic.

so you're saying that glGetTexImage returns the data for the large 'quadratic'(whatever that means) texture, and not just the texture associated with my @image? so...somewhere in all that data is the data specifically for the the texture i want?

sorry to bug you, but any more hints how i'd get just the data for my specific texture out from all that returned by glGetTexImage?

Knowing it's quadratic, you can calculate the width and height of the texture by taking the square root of the number of pixels. Then just multiply the left/top/width/height fields of the GLInfo type with the texture size and then you know where, in pixels, the relevant image data is stored. Then you have to use some array operations to select those.

how exactly does image.draw_as_quad work? i dont seem to get it to do anything XD

Same as Window#draw_quad, you supply the corners in "reading order", that is top left, top right, bottom left, bottom right. If you don't see anything, check that the colors you hand in don't have an alpha channel of zero.

got it XD

also is there a way to select the transparency of an image on draw... as far as i remember, alpha is just from total black (0) to full colour (255) right?

No, alpha is from invisible (0) to visible (255)... :) As long as the other channels are at 255, you are changing the visibility only.

thank goodness... that makes everything so much more simpler... though my mistake makes me look like a nooblet im guessing XD

by the way if you want ill send you my gosu::image rewrite (RMagick necessary) next week once its done... it adds some basic features while making others a little quicker and easier...

its mostly for my MCE but anyone can use it... you might even get some ideas from it... though i doubt it XD