API rework, round 2.

Bindings still probably broken: Python, Java, AS3, C#, Matlab, Ruby Signed-off-by: Drew Fisher <drew.m.fisher@gmail.com> (zarvox)

Author: zarvox

examples/glview.c

@@ -338,9 +338,8 @@ void *freenect_threadfunc(void *arg)
 freenect_set_led(f_dev,LED_RED);
 freenect_set_depth_callback(f_dev, depth_cb);
 freenect_set_video_callback(f_dev, rgb_cb);
-freenect_set_video_format(f_dev, current_format);
-freenect_set_video_resolution(f_dev, FREENECT_RESOLUTION_MEDIUM);
-freenect_set_depth_format(f_dev, FREENECT_DEPTH_11BIT);
+freenect_set_video_mode(f_dev, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, current_format));
+freenect_set_depth_mode(f_dev, freenect_find_depth_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_DEPTH_11BIT));
 freenect_set_video_buffer(f_dev, rgb_back);
 
 freenect_start_depth(f_dev);
@@ -364,7 +363,7 @@ void *freenect_threadfunc(void *arg)
 
 if (requested_format != current_format) {
 freenect_stop_video(f_dev);
-freenect_set_video_format(f_dev, requested_format);
+freenect_set_video_mode(f_dev, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, requested_format));
 freenect_start_video(f_dev);
 current_format = requested_format;
 }

examples/hiview.c

@@ -72,8 +72,8 @@ int freenect_led;
 
 freenect_video_format requested_format = FREENECT_VIDEO_RGB;
 freenect_video_format current_format = FREENECT_VIDEO_RGB;
-freenect_video_resolution requested_resolution = FREENECT_RESOLUTION_HIGH;
-freenect_video_resolution current_resolution = FREENECT_RESOLUTION_HIGH;
+freenect_resolution requested_resolution = FREENECT_RESOLUTION_HIGH;
+freenect_resolution current_resolution = FREENECT_RESOLUTION_HIGH;
 
 pthread_cond_t gl_frame_cond = PTHREAD_COND_INITIALIZER;
 int got_rgb = 0;
@@ -133,7 +133,7 @@ void DrawVideoScene()
 
 pthread_mutex_lock(&video_mutex);
 
-freenect_frame_size frame_size = freenect_get_video_frame_size(current_format, current_resolution);
+freenect_frame_mode frame_mode = freenect_get_current_video_mode(f_dev);
 
 if (got_rgb) {
 uint8_t *tmp = rgb_front;
@@ -151,16 +151,16 @@ void DrawVideoScene()
 
 glBindTexture(GL_TEXTURE_2D, gl_rgb_tex);
 if (current_format == FREENECT_VIDEO_RGB || current_format == FREENECT_VIDEO_YUV_RGB) {
-glTexImage2D(GL_TEXTURE_2D, 0, 3, frame_size.width, frame_size.height, 0, GL_RGB, GL_UNSIGNED_BYTE, rgb_front);
+glTexImage2D(GL_TEXTURE_2D, 0, 3, frame_mode.width, frame_mode.height, 0, GL_RGB, GL_UNSIGNED_BYTE, rgb_front);
 } else {
-glTexImage2D(GL_TEXTURE_2D, 0, 1, frame_size.width, frame_size.height, 0, GL_LUMINANCE, GL_UNSIGNED_BYTE, rgb_front);
+glTexImage2D(GL_TEXTURE_2D, 0, 1, frame_mode.width, frame_mode.height, 0, GL_LUMINANCE, GL_UNSIGNED_BYTE, rgb_front);
 }
 glBegin(GL_TRIANGLE_FAN);
 glColor4f(1.0f, 1.0f, 1.0f, 1.0f);
 glTexCoord2f(0, 0); glVertex3f(0,0,0);
-glTexCoord2f(1, 0); glVertex3f(frame_size.width,0,0);
-glTexCoord2f(1, 1); glVertex3f(frame_size.width,frame_size.height,0);
-glTexCoord2f(0, 1); glVertex3f(0,frame_size.height,0);
+glTexCoord2f(1, 0); glVertex3f(frame_mode.width,0,0);
+glTexCoord2f(1, 1); glVertex3f(frame_mode.width,frame_mode.height,0);
+glTexCoord2f(0, 1); glVertex3f(0,frame_mode.height,0);
 glEnd();
 
 glutSwapBuffers();
@@ -211,7 +211,7 @@ void keyPressed(unsigned char key, int x, int y)
 }
 }
 glutSetWindow(video_window);
-freenect_frame_size s = freenect_get_video_frame_size(requested_format, requested_resolution);
+freenect_frame_mode s = freenect_find_video_mode(requested_resolution, requested_format);
 glutReshapeWindow(s.width, s.height);
 }
 if (key == 'd') { // Toggle depth camera.
@@ -272,9 +272,9 @@ void *gl_threadfunc(void *arg)
 glutKeyboardFunc(&keyPressed);
 InitGL(640, 480);
 
-freenect_frame_size frame = freenect_get_video_frame_size(current_format, current_resolution);
+freenect_frame_mode mode = freenect_find_video_mode(current_resolution, current_format);
 glutInitWindowPosition(640,0);
-glutInitWindowSize(frame.width, frame.height);
+glutInitWindowSize(mode.width, mode.height);
 video_window = glutCreateWindow("Video");
 
 glutDisplayFunc(&DrawVideoScene);
@@ -283,7 +283,7 @@ void *gl_threadfunc(void *arg)
 glutKeyboardFunc(&keyPressed);
 
 InitGL(640, 480);
-ReSizeGLScene(frame.width, frame.height);
+ReSizeGLScene(mode.width, mode.height);
 
 glutMainLoop();
 
@@ -362,12 +362,11 @@ void *freenect_threadfunc(void *arg)
 freenect_set_led(f_dev,LED_RED);
 freenect_set_depth_callback(f_dev, depth_cb);
 freenect_set_video_callback(f_dev, video_cb);
-freenect_set_video_format(f_dev, current_format);
-freenect_set_video_resolution(f_dev, current_resolution);
-freenect_set_depth_format(f_dev, FREENECT_DEPTH_11BIT);
-rgb_back = (uint8_t*)malloc(freenect_get_video_frame_size(current_format, current_resolution).bytes);
-rgb_mid = (uint8_t*)malloc(freenect_get_video_frame_size(current_format, current_resolution).bytes);
-rgb_front = (uint8_t*)malloc(freenect_get_video_frame_size(current_format, current_resolution).bytes);
+freenect_set_video_mode(f_dev, freenect_find_video_mode(current_resolution, current_format));
+freenect_set_depth_mode(f_dev, freenect_find_depth_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_DEPTH_11BIT));
+rgb_back = (uint8_t*)malloc(freenect_find_video_mode(current_resolution, current_format).bytes);
+rgb_mid = (uint8_t*)malloc(freenect_find_video_mode(current_resolution, current_format).bytes);
+rgb_front = (uint8_t*)malloc(freenect_find_video_mode(current_resolution, current_format).bytes);
 freenect_set_video_buffer(f_dev, rgb_back);
 
 freenect_start_depth(f_dev);
@@ -378,15 +377,14 @@ void *freenect_threadfunc(void *arg)
 status = freenect_process_events(f_ctx);
 if (requested_format != current_format || requested_resolution != current_resolution) {
 freenect_stop_video(f_dev);
-freenect_set_video_format(f_dev, requested_format);
-freenect_set_video_resolution(f_dev, requested_resolution);
+freenect_set_video_mode(f_dev, freenect_find_video_mode(requested_resolution, requested_format));
 pthread_mutex_lock(&video_mutex);
 free(rgb_back);
 free(rgb_mid);
 free(rgb_front);
-rgb_back = (uint8_t*)malloc(freenect_get_video_frame_size(requested_format, requested_resolution).bytes);
-rgb_mid = (uint8_t*)malloc(freenect_get_video_frame_size(requested_format, requested_resolution).bytes);
-rgb_front = (uint8_t*)malloc(freenect_get_video_frame_size(requested_format, requested_resolution).bytes);
+rgb_back = (uint8_t*)malloc(freenect_find_video_mode(requested_resolution, requested_format).bytes);
+rgb_mid = (uint8_t*)malloc(freenect_find_video_mode(requested_resolution, requested_format).bytes);
+rgb_front = (uint8_t*)malloc(freenect_find_video_mode(requested_resolution, requested_format).bytes);
 current_format = requested_format;
 current_resolution = requested_resolution;
 pthread_mutex_unlock(&video_mutex);

fakenect/fakenect.c

@@ -194,7 +194,7 @@ int freenect_process_events(freenect_context *ctx)
 if (cur_rgb_cb && rgb_running) {
 void *cur_rgb = skip_line(data);
 if (rgb_buffer) {
-memcpy(rgb_buffer, cur_rgb, freenect_get_video_frame_size(FREENECT_VIDEO_RGB, FREENECT_RESOLUTION_MEDIUM).bytes);
+memcpy(rgb_buffer, cur_rgb, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_VIDEO_RGB).bytes);
 cur_rgb = rgb_buffer;
 }
 cur_rgb_cb(fake_dev, cur_rgb, timestamp);

fakenect/record.c

@@ -119,7 +119,7 @@ void depth_cb(freenect_device *dev, void *depth, uint32_t timestamp)
 
 void rgb_cb(freenect_device *dev, void *rgb, uint32_t timestamp)
 {
-dump('r', timestamp, rgb, freenect_get_current_video_frame_size(dev).bytes);
+dump('r', timestamp, rgb, freenect_get_current_video_mode(dev).bytes);
 }
 
 void init()
@@ -135,10 +135,9 @@ void init()
 printf("Error: Cannot get device\n");
 return;
 }
-freenect_set_depth_format(dev, FREENECT_DEPTH_11BIT);
+freenect_set_depth_mode(dev, freenect_find_depth_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_DEPTH_11BIT));
 freenect_start_depth(dev);
-freenect_set_video_format(dev, FREENECT_VIDEO_RGB);
-freenect_set_video_resolution(dev, FREENECT_RESOLUTION_MEDIUM);
+freenect_set_video_mode(dev, freenect_find_video_mode(FREENECT_RESOLUTION_MEDIUM, FREENECT_VIDEO_RGB));
 freenect_start_video(dev);
 freenect_set_depth_callback(dev, depth_cb);
 freenect_set_video_callback(dev, rgb_cb);

include/libfreenect.h

@@ -40,24 +40,29 @@ extern "C" {
 
 #define FREENECT_COUNTS_PER_G 819 /**< Ticks per G for accelerometer as set per http://www.kionix.com/Product%20Sheets/KXSD9%20Product%20Brief.pdf */
 
-/// Structure to give information about the width and height of a
-/// frame, as well as the total number of bytes needed to hold a
-/// single frame. Negative values for width and height indicate
-/// an invalid video format and resolution combination, as does
-/// a value of 0 for bytes.
+/// Structure to give information about the width, height, bitrate,
+/// framerate, and buffer size of a frame in a particular mode, as
+/// well as the total number of bytes needed to hold a single frame.
 typedef struct {
-int width; /**< Width of this frame, in pixels */
-int height; /**< Height of this frame, in pixels */
-int bytes; /**< Total number of bytes needed to hold a single frame at the given resolution and pixel format */
-} freenect_frame_size;
+uint32_t reserved; /**< unique ID used internally. The meaning of values may change without notice. Don't touch or depend on the contents of this field. We mean it. */
+int is_valid; /**< If 0, this freenect_frame_mode is invalid and does not describe a supported mode. Otherwise, the frame_mode is valid. */
+int bytes; /**< Total buffer size in bytes to hold a single frame of data. Should be equivalent to width * height * (data_bits_per_pixel+padding_bits_per_pixel) / 8 */
+int width; /**< Width of the frame, in pixels */
+int height; /**< Height of the frame, in pixels */
+int data_bits_per_pixel; /**< Number of bits of information needed for each pixel */
+int padding_bits_per_pixel; /**< Number of bits of padding for alignment used for each pixel */
+int framerate; /**< Approximate expected frame rate, in Hz */
+} freenect_frame_mode ;
 
 /// Enumeration of available resolutions.
 /// Not all available resolutions are actually supported for all video formats.
+/// Frame modes may not perfectly match resolutions. For instance,
+/// FREENECT_RESOLUTION_MEDIUM is 640x488 for the IR camera.
 typedef enum {
 FREENECT_RESOLUTION_LOW = 0, /**< QVGA - 320x240 */
 FREENECT_RESOLUTION_MEDIUM = 1, /**< VGA - 640x480 */
 FREENECT_RESOLUTION_HIGH = 2, /**< SXGA - 1280x1024 */
-} freenect_video_resolution;
+} freenect_resolution;
 
 /// Enumeration of video frame information states.
 /// See http://openkinect.org/wiki/Protocol_Documentation#RGB_Camera for more information.
@@ -271,26 +276,6 @@ FREENECTAPI void freenect_set_depth_callback(freenect_device *dev, freenect_dept
  */
 FREENECTAPI void freenect_set_video_callback(freenect_device *dev, freenect_video_cb cb);
 
-/**
- * Set the format for depth information
- *
- * @param dev Device to set depth information format for
- * @param fmt Format of depth information. See freenect_depth_format enum.
- *
- * @return 0 on success, < 0 on error
- */
-FREENECTAPI int freenect_set_depth_format(freenect_device *dev, freenect_depth_format fmt);
-
-/**
- * Set the format for video information
- *
- * @param dev Device to set video information format for
- * @param fmt Format of video information. See freenect_video_format enum.
- *
- * @return 0 on success, < 0 on error
- */
-FREENECTAPI int freenect_set_video_format(freenect_device *dev, freenect_video_format fmt);
-
 /**
  * Set the buffer to store depth information to. Size of buffer is
  * dependant on depth format. See FREENECT_DEPTH_*_SIZE defines for
@@ -429,40 +414,105 @@ FREENECTAPI int freenect_set_led(freenect_device *dev, freenect_led_options opti
 FREENECTAPI void freenect_get_mks_accel(freenect_raw_tilt_state *state, double* x, double* y, double* z);
 
 /**
- * Return the resolution implied and buffer size needed for the given
- * pixel format and resolution enum values.
+ * Get the number of video camera modes supported by the driver. This includes both RGB and IR modes.
  *
- * @param fmt Video format (pixel format) to return information about
- * @param res Resolution enum value to return information about
+ * @return Number of video modes supported by the driver
+ */
+FREENECTAPI int freenect_get_video_mode_count();
+
+/**
+ * Get the frame descriptor of the nth supported video mode for the
+ * video camera.
  *
- * @return Frame information structure, containing width, height, and
- * bytes-per-frame. If width, height, or bytes is 0, the requested
- * format/resolution combination is unsupported and can be considered
- * invalid.
+ * @param n Which of the supported modes to return information about
+ *
+ * @return A freenect_frame_mode describing the nth video mode
  */
-FREENECTAPI freenect_frame_size freenect_get_video_frame_size(freenect_video_format fmt, freenect_video_resolution res);
+FREENECTAPI const freenect_frame_mode freenect_get_video_mode(int mode_num);
 
 /**
- * Convenience function to return the resolution and buffer size for
- * the current pixel format and resolution of a given freenect device.
+ * Get the frame descriptor of the current video mode for the specified
+ * freenect device.
  *
- * @param dev Device to return current frame format information about
+ * @param dev Which device to return the currently-set video mode for
  *
- * @return Frame information structure. As in freenect_get_video_frame_size(),
- * if width, height, or bytes is 0, the requested format/resolution
- * combination is unsupported.
+ * @return A freenect_frame_mode describing the current video mode of the specified device
  */
-FREENECTAPI freenect_frame_size freenect_get_current_video_frame_size(freenect_device *dev);
+FREENECTAPI const freenect_frame_mode freenect_get_current_video_mode(freenect_device *dev);
 
 /**
- * Set which resolution the video stream should run at for a given freenect device.
+ * Convenience function to return a mode descriptor matching the
+ * specified resolution and video camera pixel format, if one exists.
  *
- * @param dev Device for which to set video stream resolution
- * @param res Desired stream resolution
+ * @param res Resolution desired
+ * @param fmt Pixel format desired
  *
- * @return 0 on success, < 0 on error.
+ * @return A freenect_frame_mode that matches the arguments specified, if such a valid mode exists; otherwise, an invalid freenect_frame_mode.
+ */
+FREENECTAPI const freenect_frame_mode freenect_find_video_mode(freenect_resolution res, freenect_video_format fmt);
+
+/**
+ * Sets the current video mode for the specified device. If the
+ * freenect_frame_mode specified is not one provided by the driver
+ * e.g. from freenect_get_video_mode() or freenect_find_video_mode()
+ * then behavior is undefined. The current video mode cannot be
+ * changed while streaming is active.
+ *
+ * @param dev Device for which to set the video mode
+ * @param mode Frame mode to set
+ *
+ * @return 0 on success, < 0 if error
+ */
+FREENECTAPI int freenect_set_video_mode(freenect_device* dev, const freenect_frame_mode mode);
+
+/**
+ * Get the number of depth camera modes supported by the driver. This includes both RGB and IR modes.
+ *
+ * @return Number of depth modes supported by the driver
+ */
+FREENECTAPI int freenect_get_depth_mode_count();
+
+/**
+ * Get the frame descriptor of the nth supported depth mode for the
+ * depth camera.
+ *
+ * @param n Which of the supported modes to return information about
+ *
+ * @return A freenect_frame_mode describing the nth depth mode
+ */
+FREENECTAPI const freenect_frame_mode freenect_get_depth_mode(int mode_num);
+
+/**
+ * Get the frame descriptor of the current depth mode for the specified
+ * freenect device.
+ *
+ * @param dev Which device to return the currently-set depth mode for
+ *
+ * @return A freenect_frame_mode describing the current depth mode of the specified device
+ */
+FREENECTAPI const freenect_frame_mode freenect_get_current_depth_mode(freenect_device *dev);
+
+/**
+ * Convenience function to return a mode descriptor matching the
+ * specified resolution and depth camera pixel format, if one exists.
+ *
+ * @param res Resolution desired
+ * @param fmt Pixel format desired
+ *
+ * @return A freenect_frame_mode that matches the arguments specified, if such a valid mode exists; otherwise, an invalid freenect_frame_mode.
+ */
+FREENECTAPI const freenect_frame_mode freenect_find_depth_mode(freenect_resolution res, freenect_depth_format fmt);
+
+/**
+ * Sets the current depth mode for the specified device. The mode
+ * cannot be changed while streaming is active.
+ *
+ * @param dev Device for which to set the depth mode
+ * @param mode Frame mode to set
+ *
+ * @return 0 on success, < 0 if error
  */
-FREENECTAPI int freenect_set_video_resolution(freenect_device *dev, freenect_video_resolution res);
+FREENECTAPI int freenect_set_depth_mode(freenect_device* dev, const freenect_frame_mode mode);
 
 #ifdef __cplusplus
 }