Torque Cookbook
by Bil Simser · in Torque Game Engine · 06/28/2004 (5:12 pm) · 20 replies
Hi guys,
Lately I've been turned onto the Cookbook type books out there (specificially the C# ones now). I spent sometime hunting down the various O'Reilly (and others) cookbook series and found them to be excellent on presentation.
If you haven't seen a cookbook, it offers a definitive collection of solutions and examples in a domain language (C++, Perl, C#, whatever). Recipes range from simple tasks to the more complex, and are organized with respect to the types of problems you'll need to solve as you progress in your experience as a programmer. Nearly every recipe contains a complete, documented code sample showing you how to solve the specific problem, as well as a discussion of how the underlying technology works and a discussion of alternatives, limitations, and other considerations where appropriate.
Here's a C# cookbook TOC:
Chapter 1 - Application Development
Chapter 2 - Working with Data
Chapter 3 - Application Domains, Reflection, and Metadata
Chapter 4 - Threads, Processes, and Synchronization
Chapter 5 - XML Processing
Chapter 6 - Windows Forms
Chapter 7 - ASP.NET and Web Forms
Chapter 8 - Graphics, Multimedia, and Printing
Chapter 9 - Files, Directories, and I/O
Chapter 10 - Database Access
Chapter 11 - Networking and Internetworking
Chapter 12 - XML Web Services and Remoting
Chapter 13 - Runtime Security
Chapter 14 - Cryptography
Chapter 15 - Unmanaged Code Interoperability
Chapter 16 - Commonly Used Interfaces and Patterns
Chapter 17 - Windows Integration
Here's a sample breakdown of Chapter 8:
8.1: Find All Installed Fonts
8.2: Perform Hit Testing with Shapes
8.3: Create an Irregularly Shaped Control
8.4: Create a Movable Sprite
8.5: Create a Scrollable Image
8.6: Perform a Screen Capture
8.7: Use Double Buffering to Increase Redraw Speed
8.8: Show a Thumbnail for an Image
8.9: Play a Simple Beep
8.10: Play a WAV or an MP3 File
8.11: Show an Animation with DirectShow
8.12: Retrieve Information About the Installed Printers
8.13: Print a Simple Document
8.14: Print a Multipage Document
8.15: Print Wrapped Text
8.16: Show a Dynamic Print Preview
8.17: Manage Print Jobs
And here's a sample of how one recipe is presented:
8.9 Play a Simple Beep
Problem
You need to play a simple sound, such as the system-defined beep.
Solution
Use an unmanaged Win32 API function such as Beep or sndPlaySound, or call the Microsoft Visual Basic .NET Beep function.
Discussion
(in depth discussion of solution and sample code)
I thought this approach would be great to have a Torque Cookbook. Right now we have Ken's excellent (and essential) book, the online documentation and API as well as a few other sources out there. Most are arranged in some kind of chronologocial fashion about moving from one section to another in the TGE and TSE. I'm just throwing out the idea of building a Torque Cookbook document/site/whatever and assembling information this way. Basically get common questions from people that come up all the time (and not so common) and put together a Toque Cookbook!
Thoughts, ideas, discussion?
Lately I've been turned onto the Cookbook type books out there (specificially the C# ones now). I spent sometime hunting down the various O'Reilly (and others) cookbook series and found them to be excellent on presentation.
If you haven't seen a cookbook, it offers a definitive collection of solutions and examples in a domain language (C++, Perl, C#, whatever). Recipes range from simple tasks to the more complex, and are organized with respect to the types of problems you'll need to solve as you progress in your experience as a programmer. Nearly every recipe contains a complete, documented code sample showing you how to solve the specific problem, as well as a discussion of how the underlying technology works and a discussion of alternatives, limitations, and other considerations where appropriate.
Here's a C# cookbook TOC:
Chapter 1 - Application Development
Chapter 2 - Working with Data
Chapter 3 - Application Domains, Reflection, and Metadata
Chapter 4 - Threads, Processes, and Synchronization
Chapter 5 - XML Processing
Chapter 6 - Windows Forms
Chapter 7 - ASP.NET and Web Forms
Chapter 8 - Graphics, Multimedia, and Printing
Chapter 9 - Files, Directories, and I/O
Chapter 10 - Database Access
Chapter 11 - Networking and Internetworking
Chapter 12 - XML Web Services and Remoting
Chapter 13 - Runtime Security
Chapter 14 - Cryptography
Chapter 15 - Unmanaged Code Interoperability
Chapter 16 - Commonly Used Interfaces and Patterns
Chapter 17 - Windows Integration
Here's a sample breakdown of Chapter 8:
8.1: Find All Installed Fonts
8.2: Perform Hit Testing with Shapes
8.3: Create an Irregularly Shaped Control
8.4: Create a Movable Sprite
8.5: Create a Scrollable Image
8.6: Perform a Screen Capture
8.7: Use Double Buffering to Increase Redraw Speed
8.8: Show a Thumbnail for an Image
8.9: Play a Simple Beep
8.10: Play a WAV or an MP3 File
8.11: Show an Animation with DirectShow
8.12: Retrieve Information About the Installed Printers
8.13: Print a Simple Document
8.14: Print a Multipage Document
8.15: Print Wrapped Text
8.16: Show a Dynamic Print Preview
8.17: Manage Print Jobs
And here's a sample of how one recipe is presented:
8.9 Play a Simple Beep
Problem
You need to play a simple sound, such as the system-defined beep.
Solution
Use an unmanaged Win32 API function such as Beep or sndPlaySound, or call the Microsoft Visual Basic .NET Beep function.
Discussion
(in depth discussion of solution and sample code)
I thought this approach would be great to have a Torque Cookbook. Right now we have Ken's excellent (and essential) book, the online documentation and API as well as a few other sources out there. Most are arranged in some kind of chronologocial fashion about moving from one section to another in the TGE and TSE. I'm just throwing out the idea of building a Torque Cookbook document/site/whatever and assembling information this way. Basically get common questions from people that come up all the time (and not so common) and put together a Toque Cookbook!
Thoughts, ideas, discussion?
#2
06/29/2004 (9:38 am)
I have a recipe or two I wouldn't mind sharing in that cookbook :) Scripting, and mainly variants on other scripts(because I'm not normal, hehe), but can probably be of help to someone once I polish it up...
#3
06/29/2004 (3:38 pm)
@Josh: I would be very happy to champion this effort as a supplement to the main documentation project going on.
#4
but so far nobody but me contributed :P
06/29/2004 (10:20 pm)
Sounds kinda like what I once started with the "TGESnipits"...but so far nobody but me contributed :P
#5
The difference here is that in the true spirit of the cookbook format, each recipe is out to state and solve a very specific problem. Looking over the snippets site, there's some of that but also a lot of general articles as well (don't get me wrong, I think it's a great resource).
The cookbook is more of a "How do I..." rather than the theory behind it. If you think about the cooking metaphor, the presentation here is getting people to cook with Torque (without putting much thought into it) rather than teaching them how to cook and what makes a good meal over another. It's like writing unit tests. The tests are very small and only test one component of a system instead of a whole suite of things.
06/30/2004 (3:01 am)
@Stefan: I agree, it's similar in concept. It's too bad there haven't been more contributions with TGESnipits as I found that to be a nice site. The difference here is that in the true spirit of the cookbook format, each recipe is out to state and solve a very specific problem. Looking over the snippets site, there's some of that but also a lot of general articles as well (don't get me wrong, I think it's a great resource).
The cookbook is more of a "How do I..." rather than the theory behind it. If you think about the cooking metaphor, the presentation here is getting people to cook with Torque (without putting much thought into it) rather than teaching them how to cook and what makes a good meal over another. It's like writing unit tests. The tests are very small and only test one component of a system instead of a whole suite of things.
#6
It would be great to start championing this. Perhaps we can start a discussion, either in this thread or a new one, detailing two things:
1) The recipes we already have (in resources, TGESnipits, and whatnot) that would be good to include
2) Additional recipes we'd like to see and how to get them coded and written-up.
Also, please email me if you want to talk about coordinating more heavily.
At the moment, I am completely overloaded, so if I'm going to be the main campaigner, organizer, or content-creator on this project, it will not get started for at least two months. But if you or someone else wants to step up and start doing serious work on this, it would totally rock, and I'd love to see work get started ASAP.
06/30/2004 (2:24 pm)
Bill,It would be great to start championing this. Perhaps we can start a discussion, either in this thread or a new one, detailing two things:
1) The recipes we already have (in resources, TGESnipits, and whatnot) that would be good to include
2) Additional recipes we'd like to see and how to get them coded and written-up.
Also, please email me if you want to talk about coordinating more heavily.
At the moment, I am completely overloaded, so if I'm going to be the main campaigner, organizer, or content-creator on this project, it will not get started for at least two months. But if you or someone else wants to step up and start doing serious work on this, it would totally rock, and I'd love to see work get started ASAP.
#7
1. Start up a new site/section to contain this stuff and start building it. Overall there should be some framework which would be a high level like TOC which covers the areas (I think most of us have done this time and time again).
2. Morph something like TGESnipits into this by putting more effort into it (with Stefan's approval/overseeing/etc of course).
With option 2, the thing is that I would want to only keep it focused on providing solutions and not theory or large scale topics. Very small and tight answers to problems. This would mean removing some content from TGESnipits as there are some "what if the sky was blue" type stuff.
Another thing is that I would see this as another resource, but not a duplicate effort. If we indeed pull from say the resources and forums directly, then I would like to see those resources removed so people don't stumble across 2, 3 or more answers to the same question (which may be different depending on who wrote the answer).
Just a couple of thoughts.
06/30/2004 (9:26 pm)
Sounds cool. A couple of options here:1. Start up a new site/section to contain this stuff and start building it. Overall there should be some framework which would be a high level like TOC which covers the areas (I think most of us have done this time and time again).
2. Morph something like TGESnipits into this by putting more effort into it (with Stefan's approval/overseeing/etc of course).
With option 2, the thing is that I would want to only keep it focused on providing solutions and not theory or large scale topics. Very small and tight answers to problems. This would mean removing some content from TGESnipits as there are some "what if the sky was blue" type stuff.
Another thing is that I would see this as another resource, but not a duplicate effort. If we indeed pull from say the resources and forums directly, then I would like to see those resources removed so people don't stumble across 2, 3 or more answers to the same question (which may be different depending on who wrote the answer).
Just a couple of thoughts.
#8
Another idea along the 'cook book' style of recipes - might be some "How NOT to" tips and or common errors that can cause problems with any recipe. Could be called recipes for disaster.
06/30/2004 (10:04 pm)
Adrian Wright and I had a conversation parallel to this about having a framework for content that should be harvested from the many code solutions shared and worked out over IRC on a daily basis. Many are reoccuring challenges for those learning Torque, but don't justify full on tutorials.Another idea along the 'cook book' style of recipes - might be some "How NOT to" tips and or common errors that can cause problems with any recipe. Could be called recipes for disaster.
#9
06/30/2004 (10:25 pm)
I agree with Jay's comment - quite often there's a lot of the same mistake made over and over (just paruse the forums a bit for good examples). A Recipes For Disaster section would be quite helpful for some people :-)
#10
06/30/2004 (11:33 pm)
I love this idea - I hope it goes forward! 
#11
I saw some posts from Melv and Brett in there--I love reading them all-->perhaps there should be a link to the TGESnippets (if not already) in the documentation...or whereever this cookbook might end up
07/01/2004 (11:57 am)
@StefanI saw some posts from Melv and Brett in there--I love reading them all-->perhaps there should be a link to the TGESnippets (if not already) in the documentation...or whereever this cookbook might end up
#12
07/01/2004 (1:36 pm)
How about a wiki? (hmm wasnt there already a wiki?)
#13
Yes, a wiki is good too. FAQ. Whatever. However the principle with this idea is that the entries are all consistent and formatted the same. With a Wiki you can just end up with lots of information that's hard to navigate. Second, a Wiki can turn into a giant dumping ground that doesn't provide very much value (unless you put a fairly large amount of work into approving Wiki pages which sort of defeats the openess aspect). It's a hard line to draw, but I think a formatted approach like this works better so you're not spending most of your time looking for stuff instead of using it.
07/01/2004 (3:38 pm)
@ThijsYes, a wiki is good too. FAQ. Whatever. However the principle with this idea is that the entries are all consistent and formatted the same. With a Wiki you can just end up with lots of information that's hard to navigate. Second, a Wiki can turn into a giant dumping ground that doesn't provide very much value (unless you put a fairly large amount of work into approving Wiki pages which sort of defeats the openess aspect). It's a hard line to draw, but I think a formatted approach like this works better so you're not spending most of your time looking for stuff instead of using it.
#14
Anyway, just an idea :)
07/01/2004 (4:11 pm)
Bil: then maybe it would be better to somehow document the "recipes" in an xml format somehow? Isn't that what xml was designed for? structuring data? With a proper DTD or XML Schema submission of entries could be streamlined because all entries will be in the best navigatable and searchable format possible, and with the right set of xpath search tools and xslt sheets this could be a nice snippit search engine.Anyway, just an idea :)
#15
Doesn't really matter what format the recipes are stored in (xml, mysql, whatever). Its the point that they're presented in a consistent and easy to find/read/use format that makes them valuable. A navigatable and searchable system is a presentation issue, not a storage one.
07/01/2004 (4:41 pm)
@ThijsDoesn't really matter what format the recipes are stored in (xml, mysql, whatever). Its the point that they're presented in a consistent and easy to find/read/use format that makes them valuable. A navigatable and searchable system is a presentation issue, not a storage one.
#16
You said a wiki might be a bad idea because of inconsistent layouts. My point was that if people submit their snippits in a specific xml format, then that problem would be solved.
Furthermore, a searchable system is also a storage issue, imho. Bad storage mechanisms make for sloppy/slow search systems.
07/01/2004 (4:46 pm)
Bil: You are missing my point :)You said a wiki might be a bad idea because of inconsistent layouts. My point was that if people submit their snippits in a specific xml format, then that problem would be solved.
Furthermore, a searchable system is also a storage issue, imho. Bad storage mechanisms make for sloppy/slow search systems.
#17
Not only would it be advisable to check the content of submissions, it would be essential to ensure that they end up in the correct category.
Submitters don't always take the time to check that they're posting in the right place, or that it hasn't already been added.
Those searching for answers don't always know exactly what they're looking for (particularly if they are beginners), so browsing can give better results.
If information isn't categorised consistently, a lot of time (and transfer/bandwidth) is wasted.
I would suggest working on the categorisation first, finding a suitable script and then appointing several admins/moderators to share the workload.
07/02/2004 (2:21 am)
I would say that some sort of moderation or administration is a must, even if it does make the submission process less open.Not only would it be advisable to check the content of submissions, it would be essential to ensure that they end up in the correct category.
Submitters don't always take the time to check that they're posting in the right place, or that it hasn't already been added.
Those searching for answers don't always know exactly what they're looking for (particularly if they are beginners), so browsing can give better results.
If information isn't categorised consistently, a lot of time (and transfer/bandwidth) is wasted.
I would suggest working on the categorisation first, finding a suitable script and then appointing several admins/moderators to share the workload.
#18
Also, I agree with your two thoughts above.
Btw, sorry about misspelling your first name in the above posts :)
07/05/2004 (11:38 am)
Bil, any more thoughts or progress on this? What's the first step? Again, I won't have the time to lead up any of this for a while. However, if I do it, I'd imagine the first steps would be identifying existing stuff we can use, and then spec'ing out the rest of what we need. Again, feel free to email me, joshw@garagegames.com if you want to coordinate more.Also, I agree with your two thoughts above.
Btw, sorry about misspelling your first name in the above posts :)
#19
07/05/2004 (1:45 pm)
@Josh: I need to put together a skeleton of how this will look. Part of that is where to spec out the source information (forums, resources, external websites, etc.) and I think a large part of it is to move that information and consolidate it which I need to discuss with you. I'll send you an email later with the plan and information and how to get things going. Thanks.
#20
07/06/2004 (1:25 am)
Sweet. Lookin forward to this.
Torque Owner Josh Williams
Default Studio Name
Right now, we have our main documentation reference project to finish up. After that, there's all kinds of great stuff planned. :) This is another very good idea to put on the heap.