gazebo.h

机器人人3D仿真工具,可以加入到Simbad仿真环境下应用。

/*
 *  Gazebo - Outdoor Multi-Robot Simulator
 *  Copyright (C) 2003  
 *     Nate Koenig & Andrew Howard
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 */

/* Desc: External interfaces for Gazebo
 * Author: Andrew Howard
 * Date: 6 Apr 2003
 * CVS: $Id: gazebo.h,v 1.87 2006/11/02 17:06:31 natepak Exp $
 */

#ifndef GAZEBO_H
#define GAZEBO_H

#include <sys/types.h>
#include <stdlib.h>
#include <stdint.h>


#ifdef __cplusplus
extern "C" {
#endif

/** @defgroup libgazebo libgazebo

See @ref libgazebo_usage for information on using libgazebo.

*/

/***************************************************************************
 * Constants, etc
 **************************************************************************/

/// @addtogroup libgazebo 
/// @{ 

/// Interface version number
#define LIBGAZEBO_VERSION 0x060

/// @}
    
/***************************************************************************/
/// @addtogroup libgazebo 
/// @{
/** @defgroup utility Error-handling
@{
*/
/***************************************************************************/

/** @brief @internal Initialize error logging
    @param print Set to 0 to stop messages being printed to stderr.
    @param level Debug level: 0 = important messages, 1 = useful
    messages, 2+ = all messages.
*/
void gz_error_init(int print, int level);
  
/** Retrieve the last error (as a descriptive string).  Most functions
    in will return 0 on success and non-zero value on error; a
    descriptive error message can be obtained by calling this
    function. */
const char *gz_error_str(void);

/** @}*/
/// @}
/***************************************************************************/


/***************************************************************************/
/// @addtogroup libgazebo
/// @{
/** @defgroup server Server object

The server object is used by the Gazebo server to establish and
maintain connections with clients.

@internal

@{
*/

/// @brief Server data
typedef struct gz_server
{
  /// The server id
  int server_id;

  /// The directory containing mmap files
  char *filename;

  /// The semphore key and id
  int sem_key, sem_cid;
    
} gz_server_t;


/// @brief Create a new server
extern gz_server_t *gz_server_alloc();

/// @brief Destroy a server
extern void gz_server_free(gz_server_t *self);

/// @brief Initialize the server
extern int gz_server_init(gz_server_t *self, int server_id, int force);

/// @brief Finalize the server
extern int gz_server_fini(gz_server_t *self);

/// @brief Tell clients that new data is available
extern int gz_server_post(gz_server_t *self);

/** @}*/
/// @}
/***************************************************************************/

  
/***************************************************************************/
/// @addtogroup libgazebo 
/// @{ 
/** @defgroup client Client object

The client object is used by Gazebo clients to establish a connection
with a running server.  See the @ref libgazebo_usage for an overview.

@{
*/

/// @brief Semaphore key used by Gazebo
#define GZ_SEM_KEY 0x135135FA
  
/// @brief Reserved client IDs.
///
/// User programs may use numbers in the range GZ_SEM_NUM_USER to
/// GZ_SEM_NUM_USER_LAST, inclusive.  All other semaphore numbers are
/// reserved.
#define GZ_CLIENT_ID_USER_FIRST 0x00
#define GZ_CLIENT_ID_USER_LAST  0x07
#define GZ_CLIENT_ID_WXGAZEBO   0x08
#define GZ_CLIENT_ID_PLAYER     0x09

  
/// Client data
typedef struct gz_client
{
  /// The server id
  int server_id;

  /// The client id
  int client_id;

  /// The directory containing mmap files
  char *filename;

  /// The semphore key and id
  int sem_key, sem_cid;

} gz_client_t;


/// Create a new client
extern gz_client_t *gz_client_alloc();

/// Destroy a client
extern void gz_client_free(gz_client_t *self);

/// Test for the presence of the server.
/// @returns The return value is 0 if the server is present; +1 if
/// the server is not present; -1 if there is an error.
extern int gz_client_query(gz_client_t *self, int server_id);

/// Connect to the server (non-blocking mode).
extern int gz_client_connect(gz_client_t *self, int server_id);

/// @brief Connect to the server (blocking mode).
/// @param self Pointer to Itself.
/// @param server_id Server ID; each server must have a unique id.
/// @param client_id Client ID; in blocking mode, each client must have a unique id.
extern int gz_client_connect_wait(gz_client_t *self, int server_id, int client_id);

/// Disconnect from the server
extern int gz_client_disconnect(gz_client_t *self);

/// @brief Wait for new data to be posted (blocking mode).
/// @returns Returns 0 on success, -1 on error.
extern int gz_client_wait(gz_client_t *self);

/** @} */
/// @}


/***************************************************************************/
/// @addtogroup libgazebo
/// @{
/** @internal @defgroup data Common data structures

All data structures share this common structure.

@{
*/

/// Max length of model type string 
#define GAZEBO_MAX_MODEL_TYPE 128

/// Common data header
typedef struct gz_data
{
  /// Interface version number
  int version;

  /// Allocation size
  size_t size;

  /// Type of model that owns this interface
  char model_type[GAZEBO_MAX_MODEL_TYPE];
  
  /// ID of the model that owns this interface
  int model_id;

  /// ID of the parent model
  int parent_model_id;
  
} gz_data_t;

/** @} */
/// @}



/***************************************************************************/
/// @addtogroup libgazebo 
/// @{
/** @internal @defgroup iface Common interface structures

All interfaces share this common structure.

@{
*/

typedef struct gz_iface
{
  // The server we are associated with
  gz_server_t *server;
  
  // The client we are associated with
  gz_client_t *client;
  
  // File descriptor for the mmap file
  int mmap_fd;

  // Pointer to the mmap'ed mem
  void *mmap;

  // The name of the file we created/opened
  char *filename;
  
} gz_iface_t;


// Create an interface
extern gz_iface_t *gz_iface_alloc();

// @internal Destroy an interface
extern void gz_iface_free(gz_iface_t *self);

// @internal Create the interface (used by Gazebo server)
extern int gz_iface_create(gz_iface_t *self, gz_server_t *server,
                           const char *type, const char *id, size_t size);

// @internal Destroy the interface (server)
extern int gz_iface_destroy(gz_iface_t *self);

// Open an existing interface
extern int gz_iface_open(gz_iface_t *self, gz_client_t *client,
                         const char *type, const char *id, size_t size);

// Close the interface
extern int gz_iface_close(gz_iface_t *self);

// Lock the interface.  Set blocking to 1 if the caller should block
// until the lock is acquired.  Returns 0 if the lock is acquired.
extern int gz_iface_lock(gz_iface_t *self, int blocking);

// Unlock the interface
extern void gz_iface_unlock(gz_iface_t *self);

// Tell clients that new data is available
extern int gz_iface_post(gz_iface_t *self);


/** @} */
/// @}


/***************************************************************************/
/// @addtogroup libgazebo 
/// @{
/** @defgroup simulator simulator 

The simulator interface provides access to certain global properties
of the server, such as the current simulation time-step. 

@{
*/

/// Common simulator data
typedef struct gz_sim_data
{
  /// Common data structure
  gz_data_t head;
  
  /// Elapsed simulator time
  double sim_time;

  /// Accumpated pause time (this interface may be updated with the
  /// server is paused).
  double pause_time;

  // Elapsed real time since start of simulation (from system clock). 
  double real_time;

  /// Pause simulation (set by client)
  int pause;

  /// Reset simulation (set by client)
  int reset;

  /// Save current poses to world file (set by client)
  int save;

} gz_sim_data_t;


/// Simulator interface
typedef struct gz_sim
{
  /// General interface info
  gz_iface_t *iface;

  /// Pointer to interface data area
  gz_sim_data_t *data;

} gz_sim_t;


/// Create an interface
extern gz_sim_t *gz_sim_alloc();

/// Destroy an interface
extern void gz_sim_free(gz_sim_t *self);

/// @internal Create the interface (used by Gazebo server)
/// @param self Point to itself.
/// @param server Pointer to the server.
/// @param id Dummy id; set this to "default".
extern int gz_sim_create(gz_sim_t *self, gz_server_t *server, const char *id);

/// @internal Destroy the interface (server)
extern int gz_sim_destroy(gz_sim_t *self);

/// @brief Open an existing interface.
/// @param self Pointer to itself.
/// @param client Pointer to the client.
/// @param id Dummy id; set this to "default"
extern int gz_sim_open(gz_sim_t *self, gz_client_t *client, const char *id);

/// Close the interface
extern int gz_sim_close(gz_sim_t *self);

/// Lock the interface.  Set blocking to 1 if the caller should block
/// until the lock is acquired.  Returns 0 if the lock is acquired.
extern int gz_sim_lock(gz_sim_t *self, int blocking);

/// Unlock the interface
extern void gz_sim_unlock(gz_sim_t *self);

/** @} */
/// @}


/***************************************************************************/
/// @addtogroup libgazebo 
/// @{
/** @defgroup camera camera 

The camera interface allows clients to read images from a simulated
camera.  This interface gives the view of the world as the camera
would see it.

Images are in packed RGB888 format.

@{
*/

/// Maximum image pixels (width x height)
#define GAZEBO_CAMERA_MAX_IMAGE_SIZE 640 * 480 * 3

/// Camera interface data
typedef struct gz_camera_data
{
  /// Common data structure
  gz_data_t head;

  /// Data timestamp
  double time;

  /// Image dimensions (in pixels)
  unsigned int width, height;

  /// Image pixel data
  unsigned int image_size;
  unsigned char image[GAZEBO_CAMERA_MAX_IMAGE_SIZE];
  
} gz_camera_data_t;


/// The camera interface
typedef struct gz_camera
{
  /// General interface info
  gz_iface_t *iface;

  /// Pointer to interface data area
  gz_camera_data_t *data;
  
} gz_camera_t;


/// Create an interface
extern gz_camera_t *gz_camera_alloc();

/// Destroy an interface
extern void gz_camera_free(gz_camera_t *self);

/// @internal Create the interface (used by Gazebo server)
extern int gz_camera_create(gz_camera_t *self, gz_server_t *server, const char *id,
                            const char *model_type, int model_id, int parent_model_id);

/// @internal Destroy the interface (server)
extern int gz_camera_destroy(gz_camera_t *self);

/// Open an existing interface (used by Gazebo clients)
extern int gz_camera_open(gz_camera_t *self, gz_client_t *client, const char *id);

/// Close the interface (client)
extern int gz_camera_close(gz_camera_t *self);

/// Lock the interface.  Set blocking to 1 if the caller should block
/// until the lock is acquired.  Returns 0 if the lock is acquired.
extern int gz_camera_lock(gz_camera_t *self, int blocking);

/// Unlock the interface
extern void gz_camera_unlock(gz_camera_t *self);

/// Tell clients that new data is available
extern int gz_camera_post(gz_camera_t *self);

/** @} */
/// @}


/***************************************************************************/
/// @addtogroup libgazebo 
/// @{
/** @defgroup factory factory

The factory interface allows clients to send XML strings to a factory
in order to dynamically create models.

@{
*/

/// Factory interface
typedef struct gz_factory_data
{
  /// Common data structures
  gz_data_t head;

  /// Data timestamp
  double time;

  /// String describing the model to be instantiated
  uint8_t string[4096];