1 files changed, 130 insertions, 0 deletions
diff --git a/iphone/doc/camera.rst b/iphone/doc/camera.rst
new file mode 100644
index 0000000..9f283dd
--- /dev/null
+++ b/iphone/doc/camera.rst
@@ -0,0 +1,130 @@
+Scanning From the Camera Feed
+=============================
+
+Many iOS developers want their application to support automatic recognition of
+barcodes from the camera feed in real-time.  ZBar makes this easy!
+
+There are three levels that you may choose to integrate at, from least complex
+(recommended) to most complex these are:
+
+* Use the fully integrated view controller - this is very easy to implement
+  and is the recommended approach.
+* Use the reader view with your own controller - this more advanced approach
+  allows you to embed the view directly in your view hierarchy.
+* Use the capture component with your own AVCapture session - this is not
+  supported and only provided for advanced developers with special needs who
+  are already familiar with AVCapture.
+
+
+Using a ZBarReaderViewController
+--------------------------------
+
+This is the fastest, easiest and recommend way to get the barcode reader into
+your application.  The procedure is the same as using a
+UIImagePickerController to take a picture with the camera, so it will help if
+you are familiar with that.  Basically you:
+
+1. Create the reader.
+
+   This is as simple as creating a new :class:`ZBarReaderViewController`::
+
+      ZBarReaderViewController *reader = [[ZBarReaderViewController alloc] init];
+
+2. Setup a delegate to receive the results.
+
+   The delegate should implement the :class:`ZBarReaderDelegate` protocol,
+   which inherits from :class:`UIImagePickerControllerDelegate`::
+
+      reader.readerDelegate = self;
+
+3. Configure the reader.
+
+   Aside from the properties of the reader itself, you can configure the
+   decoder via the :member:`~ZBarReaderViewController::scanner` property and
+   further customize the view via the
+   :member:`~ZBarReaderViewController::readerView` property::
+
+      // disable QR Code
+      [reader.scanner setSymbology: ZBAR_QRCODE
+                      config: ZBAR_CFG_ENABLE
+                      to: 0];
+      reader.readerView.zoom = 1.0;
+
+   See :doc:`custom` and :doc:`optimizing` for more details.
+
+4. Present the reader to the user.
+
+   Typically the controller is presented modally::
+
+      [self presentModalViewController: reader
+            animated: YES];
+
+   Alternatively, it may be added to a container controller.
+
+5. Process the results.
+
+   The controller will call the
+   ``imagePickerController:didFinishPickingMediaWithInfo:`` method of
+   your delegate every time new results become available.  The barcode data
+   can be obtained using the :c:data:`ZBarReaderControllerResults` key of the
+   info dictionary.  This key will return "something enumerable"; keep in mind
+   that there may be multiple results.  You may also retrieve the
+   corresponding image with :c:data:`UIImagePickerControllerOriginalImage` as
+   usual::
+
+      - (void) imagePickerController: (UIImagePickerController*) reader
+       didFinishPickingMediaWithInfo: (NSDictionary*) info
+      {
+          id<NSFastEnumeration> results =
+              [info objectForKey: ZBarReaderControllerResults];
+          UIImage *image =
+              [info objectForKey: UIImagePickerControllerOriginalImage];
+          ...
+
+   The ``reader`` parameter will be the actual type of the reader (not
+   necessarily a :class:`UIImagePickerController`).
+
+   .. note::
+
+      The delegate method should queue the interface response and return as
+      soon as possible; any processing of the results should be deferred until
+      later, otherwise the user will experience unacceptable latency between
+      the actual scan completion and the visual interface feedback.
+
+6. Dismiss the reader (or not).
+
+   Once you have the results you may dismiss the reader::
+
+      [reader dismissModalViewControllerAnimated: YES];
+
+   .. warning::
+
+      It is very important to dismiss from the *reader* (not the presenting
+      controller) to avoid corrupting the interface.
+
+   Alternatively, you may choose to continue scanning and provide visual
+   feedback another way (eg, maybe by updating your custom overlay with the
+   results).  The "continuous" mode of the readertest example does this.
+
+
+Using a ZBarReaderView
+----------------------
+
+:class:`ZBarReaderViewController` is a relatively thin wrapper around a
+:class:`ZBarReaderView`; it is possible to use the view directly, even from
+Interface Builder.  You lose only some of the simulator and rotation hooks.
+The documentation is also less complete, so you need to be able to UTSL.  See
+the :file:`EmbedReader` sample for a working example.
+
+
+Using the ZBarCaptureReader
+---------------------------
+
+If you have special requirements for the capture session or just want to use
+your own preview, you can add your own :class:`ZBarCaptureReader` to your
+session.  You must have a solid understanding of the AVCapture infrastructure
+if you plan to use this approach.
+
+.. admonition:: TBD
+
+   sorry, you're on your own here - UTSL  :)