001package com.github.sarxos.webcam;
002
003import java.awt.Dimension;
004import java.awt.image.BufferedImage;
005import java.nio.ByteBuffer;
006
007
008/**
009 * Webcam device abstraction.
010 * 
011 * @author Bartosz Firyn (SarXos)
012 */
013public interface WebcamDevice {
014
015        /**
016         * This interface should be implemented by all webcam devices supporting
017         * possibility to access raw bytes or direct bytes buffer from native webcam
018         * device.
019         * 
020         * @author Bartosz Firyn (SarXos)
021         */
022        public static interface BufferAccess {
023
024                /**
025                 * Read the underlying image memory buffer. This method will return new
026                 * reference to pre-allocated off-heap memory where image bytes are
027                 * stored. The size of this buffer is image width * height * 3 bytes.<br>
028                 * <br>
029                 * 
030                 * <b>NOTE!</b> Do <b>not</b> use this buffer to set bytes value. It
031                 * should be used only for read purpose!
032                 * 
033                 * @return Bytes buffer
034                 */
035                ByteBuffer getImageBytes();
036
037                /**
038                 * Copy the underlying image memory into the target buffer passed as the
039                 * argument.The remaining capacity of the target buffer needs to be at
040                 * least image width * height * 3 bytes.
041                 * 
042                 * @param target the buffer to which image data should be copied
043                 */
044                void getImageBytes(ByteBuffer target);
045
046        }
047
048        public static interface FPSSource {
049
050                /**
051                 * Get current device FPS.
052                 * 
053                 * @return FPS
054                 */
055                double getFPS();
056
057        }
058
059        /**
060         * Get device name.
061         * 
062         * @return Device name
063         */
064        String getName();
065
066        /**
067         * Get the list of all possible image resolutions.
068         * 
069         * @return Possible resolutions
070         */
071        Dimension[] getResolutions();
072
073        /**
074         * Get currently set image size.
075         * 
076         * @return The size which is currently set
077         */
078        Dimension getResolution();
079
080        /**
081         * Set new expected image size.
082         * 
083         * @param size the size to be set
084         */
085        void setResolution(Dimension size);
086
087        /**
088         * Fetch image from underlying camera.
089         * 
090         * @return Image
091         */
092        BufferedImage getImage();
093
094        /**
095         * Open device, it can be closed any time.
096         */
097        void open();
098
099        /**
100         * Close device, however it can be open again.
101         */
102        void close();
103
104        /**
105         * Dispose device. After device is disposed it cannot be open again.
106         */
107        void dispose();
108
109        /**
110         * Is webcam device open?
111         * 
112         * @return True if webcam device is open, false otherwise
113         */
114        boolean isOpen();
115}