It seems I lost my original Pong thread :(

[Maz]

I decided to give this another try... But at this time I took different approach. I decided to do own thread which calculates the positions and speeds of objects, and then just query those from drawing functions. But well, I am not at all sure this will work out either

Besides I am dead busy

But hey, therefore I decided to give you all a chance to participate this programming procedure I'll try to create some skeletons for components/functions, and post them in here. Then anyone can add implementation in those Only requirement I have for your implementations... Please at least check your functions do compile I will now post an unfinished skeleton of component 'BallEngine', and I will later update it... There's still some things I am not at all sure about (like whether to take the easy way out, and simply declare the ball positions etc as (static) global variables in the BallEngine file's scope.) And most of the typedefinitions I am planning to do are yet to be defined.

And finally, please ignore the {} marks. I thought I'll start writing .c file straight away, but I accidentally created quite a decent interface for this BallEngine. So this will propably create a interface for using BallEngine

Any things you see is missing from this engine? This could be thought to be an formal interface specification inspection

Code: Select all

/* ******************************************************************************** */
/*
 *    The purpose of this file is to produce an 'engine' which will 
 *    be tracking ball(s) movements. It will be launched in it's own 
 *    thread via a startup hook. At startup it will be configured
 *    by giving the initial position, speed and direction of the ball, 
 *    as well. as places of reflective walls. You can also set up
 *    an 'callback zone(s)', and if ball get's into these, a callback
 *    will be executed.
 *  
 *    After initializing thread will wait in a halt untill it is released. 
 *    After this it will keep tracking the ball's position, and tell it 
 *    when queried.
 *    
 *    The direction / velocity change can be forced via special 
 *    functions (like when hitting in the bat). Movement and reflections
 *    from walls will be autoatically calculated.
 * 
 *    Revision history
 * 
 *    -0.0.1 30.10.2007/Maz Started (first draft)
 */
 /* ******************************************************************************* */
 
 ///\brief Sets BallEngine's initial values and starts the engine's thread
 /**
  * @param SBallEngine_initvalues *sinitvals pointer to structure holding the initial values.
  * @returns ball ID or 0 if init fails.
  */
 int BallEngine_init(SBallEngine_initvalues *sinitvals)
 {
 	/* Launch the ball calculation thread and 
 	   Set initial values. */
 	
 	
 }
 ///\brief Assigns a callback function to be executed if specified ball gets into specified zone.
 /**
  * @param int ball_id ID number of the ball for which this callback is assigned
  * @param TBallEngine_callback callback_func Callback function to be executed
  * @param zone_x_left x cordinate of left vertical border of the callback zone
  * @param zone_x_right x cordinate of right vertical border of the callback zone
  * @param zone_y_high y cordinate of upper horizontal border of the callback zone
  * @param zone_y_low y cordinate of lower horizontal border of the callback zone
  * @returns amount of callback zones assigned to the ball. 0 if fails
  */
  
 int BallEngine_set_callback(int ball_id, TBallEngine_callback callback_func, zone_x_left,zone_x_right, zone_y_high, zone_y_low)
 {
 	/* Add 'callback zone' and assign the callback to it */
 	
 }
 
 ///\brief Assigns a callback function to be executed if any ball gets into specified zone.
 /**
  * @param TBallEngine_glo_callback callback_func Callback function to be executed
  * @param zone_x_left x cordinate of left vertical border of the callback zone
  * @param zone_x_right x cordinate of right vertical border of the callback zone
  * @param zone_y_high y cordinate of upper horizontal border of the callback zone
  * @param zone_y_low y cordinate of lower horizontal border of the callback zone
  * @returns amount of global callback zones assigned to the ball. 0 if fails
  */
  
 int BallEngine_set_global_callback(TBallEngine_glo_callback glo_callback_func, zone_x_left,zone_x_right, zone_y_high, zone_y_low)
 {
 	/* Add 'callback zone' and assign the callback to it */
 	
 }
 
 void BallEngine_ball_halt(int ball_id)
 {
 	
 }
 
 void BallEngine_ball_release(int ball_id)
 {
 	
 }
 
 void BallEngine_global_ball_halt()
 {
 	
 }
 
 void BallEngine_global_ball_release()
 {
 	
 }
 
 SPong_position * BallEngine_get_ball_position(int ball_id)
 {
 	//return ball's current position
 	//NULL if fails	(eg. if ball_id is invalid)
 }
 
 int BallEngine_get_ball_amount()
 {
 	//return the amount of balls
 }
 
 ///\brief retrieves IDs of all balls.
 /**
  * @param int *ball_ids array which will be filled with ball IDs. NOTE the array MUST be allocated by user.
  */
 void BallEngine_get_ball_ids(int *ball_ids)
 {
 	//check ball_ids is not NULL, and fill it with ball ids.		
 }
 
 ///\brief forces new speed and direction for a ball.
 /**
  * @param int ball_id Ball identifier
  * @param SBallEngine_heisenberg new_ball_heisenberg the new speed and position for the ball.
  * @returns the old speed and position.
  */
 SBallEngine_heisenberg BallEngine_force_change(int ball_id, SBallEngine_heisenberg new_ball_heisenberg)
 {
 	
 }

[Maz]

So let's continue thespecification work.

The purpose of BallEngine SW component is, as explained, to keep track of ball's position, and offer an interface to query it as well as provide information about the environment where the ball is. Later this can perhaps be used for other kind of games where we have moving object which bounces from walls. (Amount of balls/reflective walls is not limited, nor is the positions / sizes of walls).

Now, let's consider the data which must be kept in memory so we can define different datatypes in reasonable structures.

Code: Select all

We need:
amount of balls.
ball position (x,y coordinates)
ball speed and direction (speed as scalar value, direction with an angle from some absolute value? Or?)

position and amount of reflective walls
      -Do we wish to have some special characteristics to be defined for walls. Like increase of speed when reflection occurs, some other odd behaviour?

'callback areas'
      -position
      -associated callback function
                 -For what purposes do we wish to use callbacks. Originally I thought of creating a callback area at the non reflective walls (goals). When ball enters to the area, a callback which checks whether the ball hit on baddle or was missed and performs appropriate actions... But perhaps we should broaden our horizon.

Well, at least we need to have a position indicator. That will propably be used by other things but BallEngine, so it may be good idea to define it outside of BallEngine (on upper level). That's what type SPong_position is. So how about

Code: Select all

typedef struct SPong_position
{
        int x_coord;
        int y_coord;
}SPong_position;

Then we need the velocity structure. That will propably also be used in other places but just BallEngine. So how about:

Code: Select all

typedef struct SPong_velocity
{
        int speed;
        int angle
}SPong_velocity;

If we add mass and these two together those will accurately define something which cannot really be accurately known (according to Heisenberg). Hence naming:

Code: Select all

typedef struct SBallEngine_heisenberg
{
SPong_position position;
SPong_velocity velocity;
}SBallEngine_heisenberg;

Now, I would like to get some input regarding the callback parameters and other required types

[Maz]

I added a new function to the API:

Code: Select all

SBallEngine_heisenberg BallEngine_force_reflection(int ball_id, int speed_change, int angle_deviation);